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

Goes well beyond the destructiveHint=true annotation by explaining exactly what destruction means: omitted array fields are saved as empty rather than left unchanged, and the full record is replaced. The review-and-authorize precondition is operational context annotations cannot express.

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?

Three front-loaded sentences: what it does, then the destructive semantics, then the precondition. The parenthetical enumeration of seven array fields is somewhat redundant with the schema, but it earns its place as an explicit warning against silent data loss.

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 17-parameter destructive upsert with an output schema, the description covers the two things an agent could get wrong: clobbering fields by omission and saving without user authorization. Return values are handled by the output schema, so nothing material 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?

Schema coverage is already 88%, so most parameters self-document. The description still adds value by grouping the clear-on-omit array fields and framing the pass-through pattern (read current state, resend unchanged fields), though it does not touch the single-value fields like target_industry vs target_industries or career_switch_type.

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?

States a specific verb ('Persists') and resource ('CareerCompass data to the user's GigHQ profile'), which cleanly separates it from read siblings like get_career_compass and generative siblings like generate_career_compass. An agent can place 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?

Explicit sequencing: 'Call get_career_compass first and pass through every field the user isn't changing,' and a hard precondition that the user must have reviewed content (e.g. from generate_career_compass) and explicitly authorized saving. Names the alternative tools and the gating condition.

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