aad_show_user

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

Annotations are absent, so description carries full burden. It states 'get details' implying read-only, but does not disclose behavior like authentication requirements, error scenarios, or that it only returns one user at a time. Minimal transparency.

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?

Description is very concise with a clear structure: a one-line summary followed by an Args section listing parameters. Every sentence earns its place; no unnecessary text.

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 read tool with an output schema, the description is minimally adequate. However, it doesn't explain what 'details' includes or that the user_id is required and the UPN is optional. Slightly incomplete given its simplicity.

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 0%, so description must compensate. It adds brief explanations ('Object ID of the user', 'User principal name (alternative lookup)') to the parameter names, but does not provide full semantics like format constraints or when to use one over the other.

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?

Description clearly states verb 'get details' and resource 'Azure AD user'. This distinguishes it from sibling tools like aad_create_user or aad_list_users, which perform different actions.

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?

No guidance on when to use this tool versus alternatives (e.g., aad_list_users for listing users, aad_create_user for creating). No context provided for when it's appropriate or not.

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