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

With no annotations, the description carries the full burden and does well: it discloses that values are write-once from the bot's perspective ('your bot never sees them again'), that list returns 'names only, never values', and that allowed_hosts scopes where a secret may be sent. It omits error/overwrite behavior on re-set and what happens to references after delete.

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?

Dense and front-loaded: purpose first, then per-action param semantics, then the integration hint and quota. Every clause carries information (naming convention, host scoping, value non-disclosure) with 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 4-param mutation tool with no annotations and no output schema, the description covers parameters, secrecy guarantees, quota and consumption path. Minor gaps remain around failure modes and lifecycle after delete, which the absent output schema cannot fill.

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 0%, yet the description compensates for every one of the four parameters: name ('UPPER_SNAKE_CASE'), value, allowed_hosts with a literal example array, and the action enum's three modes with their distinct behaviors. An agent could construct a valid call from the prose alone.

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 ('Store API keys and tokens') and enumerates the three concrete actions (set/list/delete), which is more precise than the bare name 'secrets'. The '[bot-secrets]' prefix and the {{secret:NAME}} reference distinguish it from adjacent siblings like vault, store and library_get.

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 explains the consuming workflow explicitly: 'Use them with the fetch tool as {{secret:NAME}}', and the action list maps each mode to its effect. It stops short of saying when to prefer this over sibling credential stores such as vault or store, so usage context is clear but alternatives are not named.

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