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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real behavioral value by characterizing the output as advisory ('the rules are suggestions to confirm with the user') and by spelling out the intended confirm-then-save workflow rather than treating the result as final. It doesn't mention cost, latency, or limits, which keeps it short of a 5.

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 purpose and the triggering user questions are front-loaded in the first two sentences, and the return summary and save_profile handoff follow in logical order. Every sentence carries information, though the return-value enumeration is slightly redundant given the output schema exists.

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?

With an output schema present the description needn't explain return values, yet it summarizes them anyway, and it covers the parameter roles, the trigger, and the follow-up tool. For a two-parameter read tool with full annotation and schema coverage, this is essentially complete; only the absence of any note on result size or trimming for large reference sets keeps it from a 5.

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 both properties carry their own descriptions (the profile_key's irrecoverability, ref_ids as an opt-in subset), so the schema already does the heavy lifting. The description only restates that profile_key is required and ref_ids optionally narrows the reference set, adding no syntax or selection guidance beyond the schema. Baseline 3 is appropriate here.

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 names a specific verb+resource ('Describe the shared style') and immediately makes the resource concrete: the style shared across the user's references, expressed as rules for layout, type, texture, hierarchy plus a palette and tags. It is clearly distinguishable from siblings like get_profile (raw profile data) and save_profile (persisting rules), so an agent can pick it without opening the schema.

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 gives an explicit trigger condition ('when the user asks what their references have in common or wants rules to design by') with a concrete example utterance ('what is my taste?'), and it routes the agent downstream by naming the follow-up sibling: confirm the rules with the user, then keep them with save_profile. Nothing about when to reach for this tool is left to inference.

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