Who am I

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond the annotations by explaining that the tool verifies API key validity, reports identity details including persona affiliations and default selection, and indicates write permission. This is consistent with the read-only/idempotent hints; no contradiction.

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 sentences, all information-dense with no filler. The primary purpose is front-loaded, followed by usage guidance and a pointer to the related mutation tool. Every sentence earns its place.

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 zero-parameter, read-only introspection tool with no output schema and no nested objects, the description is complete: it states what the tool confirms, what it reports, how it should be used, and where to go to change the default. Nothing essential is missing for an agent to call it correctly.

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 has zero parameters, so the baseline is 4. The schema provides no properties, and the description reinforces this by describing the call as a no-input introspection request. It also clarifies the meaning of the persona-related output, which is the most relevant output field.

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 uses a specific verb ('Confirms') and identifies the exact resource being inspected: the API key and the account behind it. It enumerates the outputs (handle, personas, default persona, write permission) and is clearly distinct from siblings like list_personas or set_default_persona that manage personas rather than introspect identity.

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 explicitly guides when to call it: 'The cheapest way to debug an authentication problem, and the fastest way to find out what to pass as persona.' It also points to set_default_persona for changing the default. It does not explicitly list alternatives such as list_personas or state when not to use it, but the guidance is clear enough.

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