Generate API Key

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

Adds substantial context beyond the annotations: the response shape ('Returns `data` containing the issued key'), handling policy ('show it to the user once... do not repeat it in later messages'), the invalidation caveat ('may invalidate the previous one per backend policy'), and rejection conditions ('unauthorized sessions or policy checks may reject issuance'). This goes well past the destructive/non-idempotent hints already in 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?

Front-loaded with the action and the critical output-handling instruction; four dense sentences with no filler. Slightly packed with several distinct cautions, but each one carries operational weight.

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 an output schema exists, the description supplies the one thing the schema cannot: the secret-handling protocol and the fact that repeated calls may invalidate prior keys. For a zero-param secret-minting tool, nothing an agent needs before 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. It correctly says nothing extraneous about inputs.

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 ('Generate a new internal API key credential for the current user'), leaving no ambiguity about what the call produces. It is clearly distinguishable from the sibling tronsave_revoke_api_key (opposite action) and from login/session 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?

Explains the precondition ('Requires a wallet signature identity') but never states when an agent should mint a key versus use an existing one, nor when to prefer alternatives such as tronsave_login or tronsave_get_session_status. Usage is implied by the purpose rather than explicitly guided.

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