credentials_status

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

With no annotations, the description carries the full burden, and it delivers: it defines the two returned flags (`ready` = env vars set, `callable` = call_api currently accepts the entry) and discloses the non-obvious rule that requires_contract entries such as Serpro's are only callable once a contract exists. It never explicitly states the operation is read-only/non-mutating, which is the one 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, zero filler. The scope-defining behavior ('Without api_id...') is front-loaded before the flag semantics, and the parenthetical Serpro example earns its place by making `callable` concrete.

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?

An output schema exists so return structure need not be explained, yet the description helpfully goes further by decoding the two key output fields and their edge case. For a single-optional-parameter read tool this is essentially complete; only the absence of any statement about the tool's own auth/read-only nature keeps it from a 5.

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

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

Schema coverage is 0% and api_id has no description in the schema, so the description must compensate. It does: 'Without api_id, reports every catalog entry that requires auth' implicitly and correctly defines the omitted case as a full catalog scan, leaving the agent to infer the single-entry case. That inference is safe but not spelled out.

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 ('Show which APIs have credentials configured') and immediately scopes it further by explaining the no-argument behavior. It also distinguishes itself from call_api by defining `ready` vs `callable` in terms of what call_api will accept, so the agent can tell it apart from its siblings without reading any 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?

Gives clear context for the primary use case: with no api_id it enumerates every auth-requiring catalog entry 'so you can see what is ready to call'. This tells the agent when the tool is the right choice (pre-flight readiness check), but it names no explicit alternative to use instead and states no exclusions, so it stops short of a full 5.

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