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

Annotations already cover read-only/idempotent/open-world safety, and the description adds meaningful behavioral detail beyond them: the result is LIVE, concurrent roles are preserved rather than flattened, handle resolution costs no extra credits, not-found profiles are free upstream, and the call costs 10 Zooq credits. No contradiction exists between the description and annotations.

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 dense but every sentence carries useful information: result contents, sibling differentiation/usage criteria, parameter guidance, and cost. The first sentence is a long enumeration and the cost detail is buried at the end, preventing a perfect structure score.

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?

Given the output schema exists, return values need no deep explanation, and the description already summarizes the key result fields. It covers freshness, sibling routing, parameter choice, cost, and not-found behavior — nothing needed for correct selection or invocation appears 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?

Schema description coverage is 100%, so the baseline is 3. The schema already documents handle/entityId formats, auto-resolution, accepted aliases, and the OR relationship. The description restates this guidance rather than adding semantically new parameter information beyond the schema.

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 resource ('LIVE work history for one person') and enumerates the exact content returned: per-role organization, title, description, location, parsed dates, skills, and concurrent-role groupings. It also distinguishes itself from profile_full_experience by contrasting live data freshness against dataset-record reads. This is a precise, differentiated definition.

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 states when to use this tool ('when you need freshness, per-role skills, or correct handling of concurrent roles') and explicitly names the overlapping alternative (profile_full_experience) and why to avoid it there. It also gives parameter usage guidance (handle vs entityId), including that handle resolution has no extra credit cost and entityId skips the lookup.

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