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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a useful domain detail about the user object's default_mail_account_id, but it does not disclose other behavioral traits such as exact return shape, error behavior, or whether non-default fields are populated.

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 two short, purposeful sentences. The core action is front-loaded, and the second sentence earns its place by adding a practical downstream use that is not present in the schema or annotations.

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 one-parameter read-only getter, the description is largely complete: it names the target resource and highlights a relevant field for downstream email operations. It does not spell out the full return object, but 'Get a user' plus the specific field mention makes the expected output reasonably inferable.

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?

With schema description coverage at 0%, the description needed to compensate for the id parameter, but 'by id' only restates what the schema already signals. It adds no format, constraints, or clarification beyond the obvious meaning of the required number id.

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 clearly states a verb and resource: 'Get a user by id.' It is immediately distinguishable from the sibling list tool (hires_list_users) because it targets a single user and adds the unique default_mail_account_id detail that no other getter mentions.

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 provides a concrete use case: the returned user's default_mail_account_id can serve as from_account_id when sending emails. This gives the agent clear contextual guidance for why or when to call this tool, though it does not explicitly mention exclusions or alternative tools.

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