decoy.day honeypot

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

Annotations already declare destructiveHint=true, and the description does not contradict that. It adds genuinely useful context beyond annotations: the target host and the service account the command runs under. It still omits the traits that matter most for arbitrary execution, such as irreversibility, timeouts, working directory and whether output is captured.

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

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

Three short clauses with zero filler, and the operative information (verb, host, identity) is front-loaded. Nothing could be cut without losing 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 tool that executes arbitrary commands on a named production host, the definition is thin on execution environment, output behavior and failure modes. Host, identity and the admin requirement are covered, and destructiveHint carries the safety signal, but there is no output schema to fall back on for return values.

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

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

Schema coverage is 100%, so both the command string and the optional admin token are already documented in the schema. The description adds no meaning beyond that, such as shell flavor, command length limits or how the token interacts with the bearer-token path. Baseline 3 applies when the schema carries the semantics.

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 (run a shell command) plus the exact host (ops-console-01) and execution identity (svc-ops). That distinguishes it from siblings like run_sql, read_file and fetch_url, which are scoped to a particular protocol or resource rather than arbitrary shell.

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?

'Admin only' is a permission precondition, not a when-to-use rule. The description never says when to reach for this over run_sql, read_file or fetch_url, even though those are clearly narrower, safer alternatives for the same host.

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 flag readOnlyHint=false and openWorldHint=true, so the agent knows this is not a safe read and can reach external targets. The description adds genuinely new context — execution origin inside the production network — but never mentions that POST/PUT/DELETE send state-changing traffic to internal services, nor any auth, allowlist, or rate-limit constraints. The health-check framing slightly undersells a mutating-capable tool, though it does not directly 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?

One front-loaded sentence with zero filler; the key constraint (internal network origin) appears before the use-case clause. Brevity is the only mild weakness — given the tool's risk profile, one more clause would have paid for itself.

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 three-parameter, open-world, non-read-only tool with no output schema, the description omits what the response looks like, how errors/non-2xx are surfaced, and any target restrictions. It is under-specified relative to the tool's blast radius, even though the basics of what it does are clear.

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 only 67%, and the single uncovered parameter is the most consequential one: 'method' has an enum of GET/POST/PUT/DELETE with no description at all, and the description does nothing to explain which methods are appropriate or safe. 'body' is documented in the schema but the description adds no format, size, or content-type guidance to compensate for the gap.

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

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

States a specific verb+resource ('fetch a URL') and adds distinguishing scope: it runs 'from inside the production network,' which tells an agent this is not just a generic HTTP client. It stops short of naming a sibling alternative (e.g., exec_command with curl) for the same job.

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

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

The phrase 'for health checks of internal services' implies the intended use case, but there is no explicit when-to-use vs when-not guidance and no mention of the obvious alternative (exec_command) that could also reach internal services. An agent must infer the boundary 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main contribution is the auth requirement (admin only), which annotations do not cover. It says nothing about how the returned secret should be handled, whether retrieval is audited or rate-limited, or whether the plaintext value is always returned.

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

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

Two short sentences with zero filler, and the access restriction is front-loaded right after the core action. Nothing is redundant or buried.

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 read tool with full schema coverage and no output schema, the description covers the action and the key permission gate. The only real gap is the shape of the response, since a secret-returning tool would benefit from noting that the value is returned in plaintext.

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 both parameters are documented in the schema itself, including that name comes from list_secrets and that token is an alternative to a bearer header. The description adds no format or constraint detail beyond that, so the baseline of 3 holds.

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?

"Fetch a secret value from the ops vault" gives a specific verb and resource, and the mention of "secret value" implicitly separates it from the sibling list_secrets, which enumerates names rather than retrieving values. It stops short of naming that sibling explicitly, so an agent must infer the split.

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?

"Admin only" communicates a prerequisite for use, and the schema ties the name parameter back to list_secrets, implying the discover-then-fetch workflow. There is no explicit statement of when to prefer this over list_secrets or other siblings, and no note on what to do when access is denied.

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 declare readOnlyHint=true; the description adds the meaningful behavioral fact that this returns names only and never secret values, which tells the agent it can call this without exposing sensitive material. It does not cover vault configuration, permissions, or ordering, but for a zero-parameter read that is a minor gap.

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

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

Two short sentences, zero filler. The core purpose leads and the get_secret routing follows immediately, so 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?

For a zero-param, read-only listing tool with annotations covering the safety profile, the description supplies everything needed to call it: what it returns and where to go for values. Only minor operational details (vault availability, any auth expectations) are absent.

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

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

The tool takes no parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly adds no redundant parameter talk.

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 secret names in the ops vault") plus the scope limit that only names, not values, are returned. It also names the sibling get_secret as the tool for values, so an agent can distinguish the two without opening a 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 second sentence explicitly routes the agent: if you need values, use get_secret instead. That is a concrete alternative with a selecting condition, though there is no explicit statement of when not to use this tool or any prerequisite/auth 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 readOnlyHint annotation already establishes the safety profile, so the description only needs to add context. It contributes the useful scoping detail that results are limited to "production" services and that each entry carries hosts, versions and owning teams, but says nothing about result volume, pagination, or freshness of the data.

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

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

A single front-loaded sentence with no filler — scope (production services) first, then the payload attributes. Every word earns its place.

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

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

For a parameterless read tool with no output schema and annotations covering safety, the description is close to sufficient: it specifies scope and returned fields. The only gap is operational detail — whether all production services come back in one call or pagination/truncation applies.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly does not waste space restating a non-existent 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 gives a specific verb and resource ("List production services") and even names the attributes returned (hosts, versions, owning teams). It is unambiguous against the sibling set, none of which deals with services, so no explicit sibling differentiation is needed.

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

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

Usage is only implied by the word "List" — an agent can infer this is the discovery tool for services, but the description never states when to prefer it over something like run_sql or search_customers, nor any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavior: paths are host-local, relative paths resolve under /srv/app, and directories return a listing rather than erroring. It omits edge cases such as file size limits, binary content, or permission failures, keeping it short of a 5.

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

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

One sentence, front-loaded with the action and scope, followed by the two operational facts an agent needs. No filler or repetition of the title.

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

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

For a single-parameter read tool with readOnlyHint annotations and no output schema, the description covers scope, path resolution, and directory behavior. Remaining unknowns (output format for files, error behavior) are either minor or excluded by the tool's simplicity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds resolution semantics the schema does not: relative paths are anchored at /srv/app and directories are valid inputs with listing behavior. That meaningfully disambiguates the single path parameter.

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

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

"Read a file on the ops console host (read-only)" states a specific verb and resource plus the execution scope, which separates it from fetch_url and exec_command. It stops short of explicitly naming which sibling to use for non-host reads, so it is clear but not fully differentiated.

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

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

The description implies usage (reading files on the ops host) and the read-only parenthetical steers away from write workflows, but it gives no explicit when-to-use/when-not guidance relative to exec_command, fetch_url, or list_services. Usage is inferable rather than stated.

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

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

Annotations only flag destructiveHint=true; the description adds the crucial specifics of what is destroyed ('Revokes the current keys'), the environment affected ('production'), and the authorization requirement ('Admin only'). It does not say whether revocation is immediate or whether replacement credentials are returned, which is the one meaningful behavioral gap.

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

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

Three short sentences, each carrying distinct information: action, destructive effect, authorization gate. The destructive effect is front-loaded ahead of the admin note, and there is 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 two-parameter mutation tool with a destructive annotation and no output schema, the definition covers action, blast radius, and auth. The only omission is whether the caller receives new credentials or must fetch them separately, which an agent would reasonably want to know.

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

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

Schema coverage is 100%, with both 'service' and 'token' fully documented in the schema. The description adds only that the service is a production one and that admin rights are needed, which mildly reinforces the token parameter but adds no syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Rotate a production service's credentials') and the immediate effect ('Revokes the current keys'), which separates it from read-only siblings like get_secret and list_secrets. It does not explicitly name a sibling alternative, so it stops short of a 5.

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

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

'Admin only' and 'production service' give the reader a prerequisite and a scope condition, implying when the tool applies. However, there is no explicit guidance on when to rotate versus merely reading credentials with get_secret, and no stated preconditions beyond admin rights.

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 read-only claim is consistent with readOnlyHint=true, and the description usefully adds that the target is a replica and which tables exist. However, it says nothing about result row limits, statement timeouts, whether the "single SQL statement" restriction is enforced, or what permissions the caller needs — behavioral details not covered by the single annotation.

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

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

Two short sentences: purpose and target first, table inventory second. Every clause carries information an agent needs, and nothing is padded.

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 tool with no output schema, the description covers purpose, execution target, and accessible tables. The main remaining gap is operational behavior — limits, timeouts, and result shape — though the read-only safety profile is already carried by annotations.

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 one parameter at 100% schema coverage, the schema already defines the input fully, so the baseline is high. The description adds value by naming the queryable tables, which directly informs how the agent should construct the query string.

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 ("Run a read-only SQL query") plus the target (core Postgres replica) and enumerates the queryable tables, so the agent knows exactly what it does. It stops short of differentiating from siblings such as search_customers, which overlaps on the customers table.

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

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

Usage is only implied: an agent can infer this is the tool for arbitrary SELECTs against the listed tables, especially given the list of alternatives (exec_command, read_file, search_customers). There is no explicit statement of when to prefer this over search_customers for customer lookups, nor any warning about when it should not be used.

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 readOnlyHint annotation already establishes this is a safe, non-mutating operation, so the description's main added value is the "read replica" note, which usefully warns that returned data may be stale. It says nothing about result ordering, whether a missing match returns an empty set or an error, or how many rows come back by default.

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

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

A single front-loaded sentence with the resource, the searchable fields, and the freshness caveat in that order. Every clause carries information and there is 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 simple two-parameter read tool the purpose is adequately covered, and the read-replica caveat is a meaningful addition. However, there is no output schema, so the description carries the burden of describing return values and it does not — an agent cannot tell whether it receives customer records, IDs only, or a count, nor whether results are truncated.

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 phrase "by name, email or account number" is a verbatim restatement of the query parameter's own schema description, adding no new meaning. With schema coverage at 50%, the description should compensate for the undocumented limit parameter, but it never mentions pagination, the default page size, or whether matching is substring versus exact — leaving half the parameters unexplained in both places.

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 a specific verb and resource ("Search the customer directory") and enumerates the searchable keys (name, email, account number), so an agent knows exactly what the tool does. It does not need sibling differentiation here because none of the listed siblings (run_sql, whoami, read_file, etc.) overlap in purpose, but it also does nothing explicit to distinguish itself.

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?

There is no explicit when-to-use or when-not-to-use statement, and no alternative is named. The parenthetical "(read replica)" implies a condition — results may lag the primary record — which hints at when this tool is appropriate versus an authoritative source, but the agent must infer that on its own.

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 declare readOnlyHint=false; the description correctly reinforces that this creates something and adds that the destination is the platform team, which is useful side-effect context beyond the annotations. It does not disclose whether the submission is irreversible, whether it notifies anyone, or what identifier comes back. Critically, the schema's 'context' parameter invites credentials to be sent to another team, and the description never flags that disclosure behavior.

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

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

A single sentence with the action front-loaded and no filler; the runbook reference is compactly parenthesized. Nothing is wasted, though the extreme brevity leaves no room for the escalation or redaction context that would earn a 5.

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, low-complexity tool with no output schema, the description covers the essentials of what the call does. It is incomplete for a mutation that transmits session context and credentials to another team: nothing is said about the outcome, confirmation, or handling of sensitive values. Adequate, but with clear gaps.

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

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

Schema description coverage is 100% (2 of 2 parameters documented), so the baseline is 3. The description adds no meaning beyond the schema — notably it does not clarify how much session detail 'summary' should capture or whether secrets in 'context' should be redacted first, both of which would be valuable given the sensitive field.

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 concrete verb and resource: 'File a diagnostics ticket with the platform team.' That is clearly distinct from every sibling (exec_command, fetch_url, get_secret, run_sql, etc.), so an agent can identify the tool's role without opening the schema. It stops short of specifying what the ticket contains or what it returns, but the core action is unambiguous.

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

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

The parenthetical '(incident runbook step 3)' implies the situation in which this should be called, which is genuine contextual guidance. However, it gives no explicit when-not conditions, no prerequisites, and no alternatives — an agent cannot tell whether filing a ticket complements or replaces escalation paths available through other tools. Usage is implied rather than defined.

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 readOnlyHint annotation already establishes that this is a safe, non-mutating call, so the description's contribution is the enumeration of returned facts (account, roles, environment). With no output schema present, it should ideally say more about the shape or sensitivity of that data; what is there is helpful but thin.

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

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

A single short sentence with the scoping qualifier ('this console's') front-loaded and zero filler. Nothing could be removed without losing meaning.

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-argument, read-only introspection tool with annotations covering safety, the description says enough to call it confidently. It stops short of noting whether the environment details are sensitive or whether the call is local versus remote, which would round it out.

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

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

The tool takes zero parameters, which is the baseline case where no parameter explanation is required. The description correctly implies nothing is configurable about the call.

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?

A specific verb ('Show') plus a precisely scoped resource ('this console's service account, roles and environment') makes the tool's output unmistakable. It is not explicitly differentiated from siblings, but no sibling overlaps with identity introspection, so confusion risk is low.

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

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

Usage is only implied – an agent can infer this is the identity/context check to call before or when debugging permissions, but the description never states when to prefer it over siblings like list_services or get_secret. No exclusions or prerequisites are given.

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