Get debug credentials

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

Annotations declare readOnlyHint=true, and the description adds valuable behavioral context: it returns plaintext secrets, is 'not approval-gated', and describes parameter merging semantics ('service overrides'). This goes beyond the minimal read-only annotation without contradicting it.

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 efficient—three sentences that each carry critical information. It front-loads the purpose and then packs usage, constraints, and parameter roles. The only minor flaw is the length relative to simple tools, but nothing is wasted.

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 credential-retrieval tool with no output schema, the description covers purpose, when to use, security boundaries, parameter roles, and read-only status. However, it omits what the returned credentials look like (e.g., structure of the response) and leaves ambiguity about the 'service' parameter, which prevents a perfect score.

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

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

With 0% schema coverage, the description must compensate. It does state that 'project_id|project_name required' and that a service parameter can merge levels, but it fails to specify whether 'service' refers to service_id or service_name. It also references non-schema fields like 'auth_hint' and 'credential desc', which could confuse an agent looking for these as parameters.

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

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

The description opens with a concrete verb and resource: 'Return plaintext debug credentials (test login/password, service api-key)'. This clearly states the tool's function and distinguishes it from siblings like get_debug_session or debug_variables by specifying the exact type of data returned.

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 an explicit condition: 'Call this when has_debug_credentials/debug_credential_hints are visible and authenticated API testing is needed.' It also sets boundaries: 'do not fabricate tokens or bypass auth.' This is direct when-to-use guidance without ambiguity.

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