Read Alza user profile and address book

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 real behavioral context beyond that: the stale-token failure mode where the API may return HTTP 200 with an anonymous shape, the instruction to treat `user_id` as the binding signal, and the need to refresh via auth tools. It also discloses that the response includes HATEOAS `action` objects, which is essential for downstream calls.

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 longer than average, but every sentence carries information: purpose, contents, usage, dependency requirements, and a critical caveat about anonymous responses. It is front-loaded with the core purpose and flows logically into prerequisites and edge cases. Slightly verbose but not wasteful.

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 tool with an output schema available, the description covers all necessary operational context: the resource being read, its components, why an agent would call it, the authentication prerequisite and sequence, and the stale-token caveat that could otherwise mislead the agent. Nothing required for correct invocation is missing.

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 takes zero parameters, so the baseline is 4. The description adds no parameter semantics, which is appropriate; nothing further is needed because there is nothing to document beyond the schema's empty properties object.

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 opens with a specific verb ('Read') and a clear resource (the authenticated user's Alza profile and address book), then enumerates what is returned: personal data, the delivery-address book with HATEOAS actions, and account sections. It differentiates itself from sibling authentication and mutation tools by explaining that it supplies the `action` objects needed by other tools, leaving no ambiguity about its role.

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?

Explicit when-to-use guidance is present: 'Use to inspect the account, to confirm the account binding, and to obtain the `action` objects required by...'. It also states the prerequisite (loaded mobile API access token), the order to follow (`account_status` first, then `auth_start`/`auth_exchange`), and when to refresh the token. No alternative is named, but the usage context is fully specified.

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