List Personas

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

Annotations already declare readOnlyHint=true. The description adds valuable behavioral details: secret values are always masked, plain values never leave the server, and project context is required. This exceeds what annotations provide, though it could mention pagination or the default list behavior.

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?

The description is concise, front-loaded with the primary purpose, then the optional parameter, then the masking behavior and requirement. Every sentence earns its place with no fluff.

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 simple list tool with one optional parameter and no output schema, the description covers purpose, parameter usage, security masking, and a prerequisite. It does not explicitly state that omitting personaId returns all personas, but this is implied by 'List.' Overall, it is sufficiently complete.

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 100%, and the schema already explains personaId as a Guid that returns a single persona. The description's 'Pass personaId to get a single one' adds no new meaning beyond the schema, so it stays at the baseline.

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 ('List'), resource ('security personas'), and scope ('of the active project'), and clarifies what personas are ('the identities the authorization scanners impersonate'). This clearly differentiates it from sibling tools like test_persona or list_security_guidance.

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?

The description indicates when to use the tool (to list personas) and notes the prerequisite 'Requires project context.' It does not explicitly contrast with alternatives, but the purpose is self-evident and the context requirement is a clear guideline.

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