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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds what the annotations cannot: the existing primary CV file is replaced and not kept, sign-in to techjobs.vn is required, and the first call in the replace case is a silent dry-run. That is exactly the behavioral context an agent needs before a destructive write.

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?

Four sentences, front-loaded with the auth prerequisite and the destructive consequence before the procedural detail. No filler and no repetition of the title.

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 two-parameter destructive mutation with no output schema, the description covers auth, data loss, the dry-run return behavior, and the confirmation loop. Nothing an agent needs in order to call it safely 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 100%, so the baseline is 3, but the description adds the sequencing that gives confirm_replace its meaning (dry-run first, then repeat with true) and constrains cv_id to editable CVs. It stops short of restating the source tools for cv_id, which the schema already names.

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 and resource ("Makes one of the user's editable CVs their primary CV") plus the domain gloss "CV chính, used for matching and referrals", which separates it from update_cv_variant and create_cv_variant in the sibling list. An agent can identify the tool 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?

Gives an explicit gate ("call it only when the user asked") and a concrete two-step protocol: if a primary CV exists, the first call is a no-op that reports what would be replaced, then repeat with confirm_replace true after asking the user. This is when-to-use and when-not-to-proceed guidance rather than inference.

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