Configure Safefy Credentials

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

Annotations already disclose the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description layers on genuinely useful non-structured context: an operational gate flag, the recommended env-var path, and a security caution about handling secretKey. It stops short of saying whether existing credentials are overwritten, which matters for a non-idempotent write.

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, no filler, and the gating precondition is front-loaded before the recommendation and the caution. Every sentence carries a distinct operational instruction.

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-setting mutation with no output schema, the description covers the prerequisite, the preferred alternative, and the security constraint. The remaining gap is the effect of the call itself (overwrite behavior, error outcome when credentials are rejected), but the essentials for correct invocation are present.

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 67%, with publicKey and secretKey documented by format hints (pk_/sk_ sandbox/production) but authenticateNow carrying no description. The description adds no parameter semantics of its own, only env-var names, so the undocumented third parameter remains unexplained in both places; baseline 3 for this coverage level.

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 ('Configura as credenciais da conta'), so the agent knows this sets payment credentials rather than reading them. It does not explicitly name a sibling (e.g. get_configuration or authenticate) to disambiguate, but the resource is narrow enough that confusion is unlikely.

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 a concrete precondition (only works if the operator enabled SAFEFY_ALLOW_CHAT_CREDENTIALS=true) and recommends the env-var route instead, plus a safety rule about not requesting the secretKey in chat when disabled. That is clear when-to-use and when-not context, though it never points to a specific alternative tool.

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