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

Annotations already flag this as a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds value beyond that by disclosing the return value ('Returns `saved`') in the absence of an output schema, and by stating the grounding constraint ('Use only facts the person stated, never invented numbers'). It does not say whether reusing an existing `id` overwrites or errors, which is the notable remaining gap.

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 what the tool does before the routing guidance and parameter notes. Dense but every clause carries information; the backticked identifiers keep it scannable. Slightly packed, but no filler.

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 7-parameter write tool with no output schema, the description covers the key operational facts: where `role` originates, its default semantics, the grounding rule for content, and the return value. Remaining fields (tags, metrics, text_es, profile) are fully documented in the schema, so nothing critical 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 description coverage is 100%, so baseline is 3, but the description adds cross-tool semantics the schema cannot: `role` comes from upsert_role, and omitting it scopes the bullet to Selected Impact only. That is meaningfully more than the schema's 'Role id from profile.yaml this bullet belongs to.'

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 ('Add one achievement to the bullet pool') and immediately defines what the resource is ('the material every CV variant picks from'). Distinguishes it from save_variant, which governs which bullets a CV shows, so an agent can route correctly 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 when-to-use ('after the person approves the wording, one bullet per call'), an explicit alternative ('to change which bullets a CV shows, use save_variant'), and a defaulting rule for the `role` parameter. Both inclusion and exclusion conditions are covered.

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

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

Annotations cover only the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), but the description goes further: it discloses overwrite semantics ('replacing earlier builds of the same variant and language'), the default output location, the return payload (files, pages, ats_ok, failed checks), and even what to do on failure ('report it, never reword the person's text'). That is unusually rich behavioral context.

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?

Front-loads the core action and the routing guidance before the file/return details; each sentence carries distinct information. It runs slightly long across five sentences, but none are padding.

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 mutation tool with no output schema, the description supplies the return contents (files, page counts, ats_ok, failed checks), the output destination, the overwrite behavior, and failure-handling policy, so an agent has everything needed to call and interpret it correctly.

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 all five parameters (lang, formats, out_dir, profile, variant) are already fully documented in the schema; the description adds only the variant+language replacement rule and restates the out_dir default. Baseline 3 is appropriate since the schema does the heavy lifting.

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+resource ('Render a CV variant to PDF and/or DOCX') plus a secondary action (ATS verification), and explicitly names the siblings it is not: build_letter for cover letters and verify_pdf for PDFs made elsewhere. An agent can distinguish it from all 30 siblings without opening a 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 trigger ('use it when the person wants the files') and two named alternatives with the conditions that select them (cover letter -> build_letter; PDF made elsewhere -> verify_pdf). Nothing 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.

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

Discloses a real behavioral trait beyond the annotations: the tool re-runs check_claims and refuses while problems exist, and returns files and warnings to show the person. Annotations only cover the safety profile (readOnly=false, destructive=false), which the description is consistent with, so the validation gate and return shape are genuine added value.

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 tight sentences, front-loaded with what it renders and immediately followed by prerequisites, the sibling alternative, and the guard behavior. Every clause carries information with no repetition of name or 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?

No output schema exists, yet the description explains what is returned (files and warnings). Combined with 100% schema coverage on 11 parameters and the stated prerequisite chain, an agent has everything needed to invoke it correctly.

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 11 parameters are already fully documented in the schema. The description adds only tangential mapping ('with the CV's ATS checks' relating to keywords) and no format or syntax detail beyond the schema, so the baseline 3 applies.

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 (render) and resource (approved cover letter) plus output formats (one-page PDF and/or DOCX), and explicitly names the sibling it is not (build_cv) for the CV itself. An agent can distinguish this from build_cv without opening either 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 explicit sequencing preconditions ('after drafting the letter with the person and running check_claims') and routes to the alternative ('for the CV itself use build_cv'). The when-to-use and the sibling boundary are both stated outright.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the trailing 'Read-only' is largely redundant; however the description adds substantial value beyond the annotations by disclosing the return structure (problems vs warnings), what each contains, and the required remediation policy ('remove or qualify, never add skills'). This behavioral guidance is not inferable from structured fields.

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?

Front-loaded with the purpose in the first clause, then usage, return shape, and remediation in a tight sequence. It is slightly dense with parenthetical examples but every sentence earns its place with no filler.

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 no output schema, the description correctly carries the burden of explaining the return value (problems and warnings, with examples of each). Combined with the remediation guidance and the pointer to sibling tools that reuse it, an agent has everything needed to call and act on this tool.

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 text, profile, and keywords are fully documented in the schema. The description reinforces the profile-relative nature of the check but adds no syntax or format detail for the individual parameters, so the baseline 3 applies.

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 ('check') and resource ('any text about the person against their profile') and carves out scope by naming the related tools (build_letter, linkedin_profile) that invoke it internally. An agent can distinguish it from siblings like build_letter or verify_pdf without opening a 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 a clear trigger — 'before it goes anywhere' — and enumerates the artifact types it applies to (cover letter, summary, LinkedIn text), plus notes that build_letter and linkedin_profile run it automatically. It does not state explicit exclusions or name a competing tool to prefer instead, so it falls just short of 5.

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

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

Annotations only declare the generic write/safe/local profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description goes well beyond them: it discloses the 10-upgrades-per-call confirmation batching, the auto-save behavior for keep/lower lines, and names the exact return fields (counts, pending_evidence, skills_without_achievements, key_skills_without_achievements).

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 core operation and its re-invocation rule are front-loaded in the first sentence, and the rest is dense but mostly load-bearing (return fields, follow-up ordering). It is longer than typical and blends downstream agent instructions with tool semantics, which costs a point, but little is redundant.

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 stateful, form-driven write tool with no output schema, the description covers when to call it, what it persists automatically vs. confirms, what the response contains, and what the agent should do next (achievements first, then key skills, gap_report fallback). Nothing an agent needs to invoke it correctly 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 description coverage is 100%, so both `path` and `profile` are already documented in the schema, including the default-profile fallback. The description adds no syntax or format detail for the parameters themselves, so baseline 3 applies.

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?

Opens with a specific verb+resource: 'Save the skills the person marked in a checklist file.' It explicitly anchors itself to the sibling workflow ('after checklist_new', 'save with set_skills'), so an agent can distinguish it from checklist_new, set_skills, and add_bullet without opening any 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 explicit triggering conditions ('after checklist_new, once the person says they are done, and again to resume') and an explicit re-invocation rule ('call again while upgrades_not_asked_yet is not empty'). It also states what NOT to do ('Ask about nothing else', 'Never write an achievement for them'), which is unusually complete routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the trailing 'Read-only' restates structured data and adds nothing. However, the description goes beyond the annotations by disclosing the return payload (checklists with id, title, description, skills count, origin) and the origin semantics ('built-in' vs 'yours' for templates in <profile>/checklists/), which is genuinely useful behavior detail.

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?

Front-loaded with purpose, then usage, then return shape — a sensible ordering. Slightly dense, and the closing 'Read-only' is redundant with annotations, but no sentence is wasted overall.

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?

No output schema exists, yet the description enumerates the returned fields and the origin values, so an agent knows exactly what it will receive. Combined with the routing guidance to checklist_new, nothing needed to call this correctly 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 description coverage is 100%, so the baseline is 3. The description still adds meaning by explaining why lang matters ('Pass `lang` in the person's language to get the translated templates'), which clarifies the translation behavior of that parameter beyond the schema's terse wording.

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 ('List the skill checklist templates') and immediately qualifies scope ('the person can combine'), which separates it from checklist_new, checklist_apply and the other checklist siblings. An agent can identify what this does 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 explicit sequencing guidance ('Use it before checklist_new, to let the person pick the ones that fit their profession'), naming the alternative tool and the condition that selects it. It also clarifies applicability ('Any profession works'), removing a common hesitation point.

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

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

Discloses behavior beyond annotations: refuses to replace an existing file unless overwrite is set, dedupes templates, prefills from inventory, and returns path plus skill count. Annotations only cover the safety triad, so these are genuine additions. Minor gap: no info on whether a partial read/write or permissions are involved.

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?

Compact and front-loaded with purpose, then usage, then next-step, then behavioral guarantees. Slightly dense with three ideas packed into single sentences, but no waste.

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?

Covers purpose, workflow position, cross-parameter interaction, refusal behavior, and return value despite no output schema. Nearly complete for a file-producing tool; only missing error/edge-case behavior.

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 schema already documents all six parameters with defaults and the lang enum. The description only adds that lists may be empty when extra supplies skills, a useful cross-parameter constraint but otherwise baseline.

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 ('Write a checklist file... merged from the templates picked in checklist_list') and distinguishes itself clearly from siblings by naming checklist_list as its upstream source and checklist_apply as its downstream step.

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?

Explicitly gives the when-to-use condition ('Use it when the person has many skills: it is much faster than asking one by one') and names the alternative workflow (asking one by one), then routes to the next tool (checklist_apply).

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

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

Annotations only tell the agent it is a non-read-only, non-destructive, closed-world write; the description adds substantive behavior beyond that: the honesty filtering rule (X skills never appear, F skills only in a Familiarity group), the write destination and its default, and the returned path. This is genuinely useful context the structured fields do not carry.

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?

Front-loads the core purpose, then the alternative, then the behavioral rule, then the output detail. Every sentence carries distinct information with no filler.

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 4-parameter write tool with no output schema, the description covers what is produced (a JSON Resume file), where it is written (out_dir with default), what is returned (path), and the content-filtering rule. Nothing an agent needs to call it correctly 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 description coverage is 100%, so the schema already documents lang, out_dir, profile, and variant. The description restates the out_dir default and return path but adds no new parameter meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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 (export) and resource (a CV variant as a JSON Resume file) with the target audience/format named. It explicitly distinguishes itself from the sibling build_cv, which produces PDF/DOCX, so an agent can route between the two without opening schemas.

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 alternative: 'Use build_cv for a PDF or DOCX instead.' This is exactly the when-to-use-this-vs-sibling guidance the dimension rewards, with the format condition that selects each tool made clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description's 'Read-only' merely echoes that. The real value is the disclosed response shape: five named buckets with the prescribed action for each (add via unused_bullets, treat as familiarity only, do not claim, ask for an achievement, ask where it was used), which no annotation or schema conveys. It stops short of describing ordering, size, or how counts are derived.

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?

One dense paragraph, but front-loaded: purpose first, then usage and ordering, then the return-value breakdown. Every clause carries information, though the bucket list makes it long and could have been structured as a short list for faster scanning.

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 no output schema, the description carries the burden of explaining what comes back, and it does so thoroughly for all five result groups plus their intended follow-up actions. Combined with the explicit workflow placement, an agent has everything needed to call and act on the result.

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 all five parameters (variant, keywords, preferred, profile, lang) are already documented in the schema. The description adds only indirect hints, such as keywords being the job post's own wording and the mention of `unused_bullets` as a source, which does not go beyond the structured fields.

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: 'Explain the keywords a job post asks for that one variant doesn't show', with the grouping dimension ('by what can honestly be done') that makes the output meaningful. It is clearly distinguishable from siblings like score_job, save_variant and check_claims.

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 explicit sequencing: 'Use it after score_job picked the variant, before editing it with save_variant.' This places the tool in the workflow between two named siblings, so an agent knows exactly when it applies and when it is premature or too late.

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

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

Annotations already cover the safety profile via readOnlyHint/openWorldHint, and the trailing 'Read-only' largely repeats that. However, the description adds genuine behavioral value by describing the return payload (levels, skills grouped by level, per-skill years/last_used_year/evidence/aliases/notes), which matters because no output schema exists. No permissions, limits, or error behavior are discussed, keeping it below 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?

Three tight sentences, front-loaded with purpose then usage then return shape. The final 'Read-only' clause is redundant with the readOnlyHint annotation, a minor amount of wasted space.

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 single-optional-parameter read tool this is fully adequate: it covers purpose, timing, sibling routing, and enumerates the returned structure in place of the missing output schema. Nothing needed to call it correctly is absent.

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?

Only one optional parameter with 100% schema description coverage, so the schema already explains the profile path and its default resolution. The description adds no additional meaning about the parameter, which is the baseline 3 case.

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 ('Read the person's skill inventory') and immediately distinguishes it from the sibling that handles CV content (list_variants). An agent can select this tool without opening any 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 explicit timing ('at the start of a session and before proposing skill changes') and names the alternative tool plus the condition that selects it ('for CV content (roles, bullets, variants) use list_variants instead'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations only say it is not read-only, not destructive, not open-world; the description goes well beyond that by disclosing add-only merge semantics ('only what the profile lacks, never overwriting'), where level-less skills land (<profile>/imported-skills.md, not the inventory), that bullets are tagged 'imported', and that for a PDF nothing is written and the text is returned instead. This is exactly the extra context annotations cannot carry.

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?

Purpose and formats are front-loaded, then details follow in roughly descending importance (what is written, skill handling, tagging, return value, PDF exception). It is dense and semicolon-heavy, but nearly every clause carries operational information; only the format list is redundant with the schema.

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?

Despite having no output schema, it describes the return payload ('what was added' plus an optional note) and the PDF return ('the text'). For a multi-format, additive write tool, the write scope, non-overwrite guarantee, tagging side effect, and dry-run path cover everything an agent needs to call it correctly.

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, but the description adds real usage meaning for dry_run by prescribing 'run it first with dry_run' as the intended first call rather than leaving the flag's role to the schema alone. It also restates the path formats already in the schema, adding no new detail there.

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+resource ('Import an existing CV into the profile') and enumerates the exact accepted formats (.json JSON Resume, .zip LinkedIn export, LinkedIn PDF). It also situates itself relative to siblings ('right after init_profile', 'instead of typing everything'), so an agent can place it in the workflow without opening another 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 about when to use it ('at the start, right after init_profile'), the recommended sequence ('run it first with dry_run'), and routes the PDF sub-case to the import_linkedin_pdf prompt for organizing text with editing tools. Alternatives and timing are both named.

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

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

Annotations already declare destructiveHint=false and openWorldHint=false, so the safety profile is largely covered. The description adds genuinely new behavior: it refuses an existing profile, overwrites nothing, and names the returned key ('created': the files written). It stops short of describing failure ordering or permissions, hence 4 rather than 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?

Three sentences, each earning its place: purpose, usage/alternative, safeguards and return. The most decision-relevant content (what it creates and when to call it) is front-loaded.

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?

No output schema exists, but the description compensates by naming the returned field. Combined with the refusal/no-overwrite guarantees and the pointer to import_profile, an agent has everything needed to call this correctly in one shot.

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 the single parameter is already fully documented ('Folder to create. Must not hold a profile yet.'). The description adds a return-value note rather than parameter meaning, so the schema carries the load and baseline 3 applies.

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 ('Create a new profile folder') and enumerates the artifacts produced (profile, bullets, skills, variants YAML templates). It also distinguishes itself from the sibling import_profile, which imports existing data rather than scaffolding empty templates.

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 timing ('Use it once, before anything else, when the person has no profile') plus a named alternative and the condition that selects it ('to start from LinkedIn or a JSON Resume, call import_profile afterwards'). The precondition is unambiguous.

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

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

With annotations declaring readOnlyHint=false and destructiveHint=false, the description adds real behavioral context: the write path persists to <profile>/prep/<id>.md and 'replacing earlier notes', disclosing an overwrite that the annotations don't surface. It stops short of permission/auth or failure behavior, so 4 rather than 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?

Front-loaded with the purpose and then the call sequence, and nearly every clause adds operational detail. It is dense and slightly run-on ('those in the CV they sent first'), but there is little dead weight.

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 5-parameter tool with no output schema, the description covers the whole cycle: inputs per call, the returned fields (level, evidence, stories, standing), the enumerated standing meanings, and the persistence side effect. Nothing essential is left for the agent to guess.

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 operative meaning the schema cannot: `keywords` must be in the post's own wording and pulled from the first call's `post_text`, and `notes` is what the person approved. It explains how keywords/preferred drive the returned keyword breakdown rather than just restating them.

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 ('prepare the interview for one logged application') and frames the scope as grounding prep in what the candidate can honestly back up. No sibling tool does interview prep, so the agent can distinguish it immediately.

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 two-call protocol: first with only `application` to retrieve the saved post, then again with the post's keywords, plus the optional `notes` path for saving. It also prescribes what to say aloud for each `standing` value, which is genuine when/how guidance.

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

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

Annotations declare a non-read-only, non-destructive, closed-world write, and the description adds real behavior beyond that: it emits a Markdown file to copy from, returns `path`, and returns `left_out` for bullets that didn't fit. It also discloses that approved headline/About are 'checked like a letter' and replace the draft. It doesn't say whether a re-run overwrites a prior file, which is the main remaining gap for a file-writing tool.

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 is front-loaded, but the prose is tangled — the final sentence about re-calling with approved headline/About ('checked like a letter') is convoluted and would read better as a discrete instruction. Sentences earn their place but are not tight.

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 no output schema, the description correctly carries the return contract (`path`, `left_out`), which is what an agent needs. It is largely complete for a 6-parameter write tool; overwrite/idempotency behavior and the src of skills data are the only notable omissions.

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 workflow meaning the schema doesn't carry: `headline` and `about` are the approved/polished versions that supersede drafts and are persisted to the file. It also frames `variant` as the driver of per-position descriptions and skills filtering.

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 and resource set: it writes headline, About, per-position descriptions, and skills for a variant, within LinkedIn's limits, to a Markdown file. That scope is specific enough to distinguish it from build_cv, build_letter, and the set_* mutators in the sibling list.

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 the triggering context explicitly ('Use it when the person updates their LinkedIn profile') and gives a second, conditional use case: re-call after approval with the polished headline/About. It does not name any alternative tool or say when not to use it, so it stops short of a 5.

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

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

With no output schema, the description carries the return-value burden and does so explicitly: the `applications` array with id/status/days_since_update, per-status counts, and the non-obvious definition of `waiting` (open, no news for 14+ days). The closing 'Read-only' partly restates readOnlyHint but the return semantics are genuinely additive.

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 tight sentences, front-loaded with purpose then usage then return shape. No filler; each clause (trigger, sibling routing, return fields, `waiting` definition) earns its place.

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 read-only, two-optional-param list tool with no output schema, the description supplies everything an agent needs: when to call it, what it returns, and the meaning of the derived `waiting` field. 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 description coverage is 100% for both `status` (enum list, default all) and `profile` (default path resolution), so the schema already does the work. The prose only references status indirectly via the per-status counts and adds no filtering syntax or default behavior beyond it.

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?

Names a specific verb+resource ('List the person's job applications') and adds scope/detail (sort order 'most recently updated first'). It clearly contrasts against the write-path sibling log_application, so an agent can distinguish it without opening schemas.

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 trigger ('when they ask how their search is going or which application to follow up') and names the alternative ('log_application records changes'), making the read-vs-write split unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description's 'Read-only' only restates that. However, without an output schema the description usefully discloses that the resolution is pre-computed ('extends already applied') and what comes back ('own', 'unused_bullets'), which the agent cannot get from structured fields.

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 tight sentences with the purpose front-loaded, followed by usage routing and return shape. Slightly dense with backtick-laden field names, but every sentence carries information.

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-required-parameter, read-only list tool with no output schema, the description covers purpose, when to call it, and the merged/resolved return structure including derived fields. Nothing critical 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?

Schema description coverage is 100% and the single 'profile' parameter is fully documented with its default fallback in the schema. The description adds nothing about parameters, so the baseline 3 applies.

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 ('Read every CV variant') and adds scope detail that distinguishes it: 'extends already applied' and 'the text of each bullet it uses'. An agent can tell this apart from save_variant, build_cv or score_job immediately.

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?

Explicitly names three sibling tools (save_variant, build_cv, score_job) as the operations to precede and states the reason ('to know what each CV contains'). This is direct when-to-use routing rather than inferred context.

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

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

Goes well beyond the annotations (readOnly=false, destructive=false, openWorld=false) by disclosing merge semantics ('Fields not given keep their value'), a real side effect (each file is copied to <profile>/sent/<id>/), and the return payload including the not_found list. That is exactly the behavioral context an agent needs before mutating.

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?

Front-loaded with purpose and trigger, and every sentence carries information, but the middle is a dense run of embedded rationale and side-effect clauses rather than cleanly separated points.

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?

No output schema exists, yet the description explains what is returned (application and not_found), and it covers merge behavior, file side effects, and profile resolution for a 12-parameter mutation tool. Nothing an agent needs to call it correctly 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 description coverage is 100%, so the baseline is 3, but the description adds rationale the schema lacks: save the post's full text because 'links expire', and use `prep` for interview advice. It leaves the remaining params (status, notes, variant, lang) to 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?

States a specific verb and resource ('Record a job application') plus the upsert key ('or update the one for the same company and role'), which is the behavior an agent most needs to know. It also implicitly distinguishes itself from list_applications by noting that sibling 'reads them back'.

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 concrete triggers: 'when the person sends a CV or letter, and whenever they tell you what happened (interview, offer, rejection)'. It routes reads to list_applications, but offers no explicit when-not-to-use or prerequisite guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds materially: the deletion is irreversible ('it cannot be undone'), requires human confirmation, propagates to every variant, and reports back 'what was removed and variants_updated'. This is context the structured fields do not carry.

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 sentences, zero waste: scope first, then routing, then the irreversibility warning. The most consequential information (destructive, irreversible) is front-loaded.

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?

No output schema exists, yet the description covers the return value ('what was removed and variants_updated'), the reversibility profile, the confirmation requirement, and the alternative path. Nothing needed to call this correctly 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 description coverage is 100% and both parameters (id, profile) are documented in the schema, so the description adds no syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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 ('Delete an achievement') plus its blast radius ('from the pool and from every variant that uses it'). It explicitly contrasts with the sibling save_variant, so an agent can route without opening either 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 when-to-use ('when the person wants it gone'), an explicit alternative with its condition ('to stop showing it in one CV, change that variant with save_variant instead'), and a prerequisite ('Ask the person first'). Nothing 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.

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description still adds genuinely new behavioral facts the annotations cannot express: the cascade across variants, that it cannot be undone, and the response shape (what was removed plus variants_updated).

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 sentences, no waste; the destructive scope is front-loaded, the alternative follows, and the safety warning and return contract close it out. Every sentence earns its place.

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 destructive 2-parameter tool with no output schema, the description supplies the cascade semantics, irreversibility warning, alternative routing, and a statement of return values — everything an agent needs to invoke it safely and correctly.

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% and both parameters (id, profile) are fully documented in the schema, so the baseline is 3. The description mentions `publications` and `variants_updated`, but those belong to sibling tools/the response, not to this tool's own input parameters.

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 (delete) plus resource (publication) and, crucially, the scope: from the profile AND from every variant that lists it. This distinguishes it from sibling mutation tools like save_variant without requiring the caller to open a 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?

Explicitly names the when-not condition and the alternative: to hide it from one CV only, change that variant's `publications` with save_variant instead. It also adds a consent prerequisite ("ask the person first") and the irreversibility constraint.

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

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

Annotations already flag destructiveHint=true, but the description adds substantial context beyond them: the refusal when bullets exist, the fact it spans all variants, that it cannot be undone, and to confirm with the person first. Only return-shape detail ('variants_updated') is thin, but no output schema exists so this is a minor gap.

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?

Front-loads the core action, then the refusal rule, then the alternative, then the caution. Four tight sentences, no redundancy, every clause carries operative information.

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?

Covers purpose, refusal condition, cross-variant scope, alternative tool, irreversibility, and return keys, which is thorough for a 3-param destructive tool. Missing only explicit permission/authorization requirements, but the 'ask the person first' cue partially fills that.

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 baseline is 3. The description still adds meaning: it explains the conditional behavior of with_bullets (only deletes bullets when true and agreed) and implies id must be a valid role with bullets. Slight added value over the schema's own text.

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+resource (delete a role) and immediately scopes it to the profile and every variant. Names and distinguishes from the sibling save_variant, clarifying this is a global delete, not a per-CV hide.

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-vs-alternative: to hide a role from one CV, use save_variant instead. Adds the guardrail that a role with bullets is refused unless with_bullets is true, so the agent knows the exact condition that makes the call succeed.

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

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

Annotations already flag destructiveHint=true, but the description goes further: it states the change cannot be undone, that it cascades to variants' skill groups and competencies, and that the response contains the removed item plus variants_updated. That is genuine behavioral context the annotations do not carry.

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?

Every sentence earns its place: operation scope first, then the alternative-use rule, then the irreversibility warning, then the return shape. No filler and the critical scoping constraint is front-loaded.

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?

No output schema exists, yet the description still describes the return payload (removed item and variants_updated), and it covers scope, safety and routing. Nothing an agent needs to call it correctly 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 description coverage is 100%, so both parameters (name, profile) are already documented in the schema. The description only implies the skill is identified by name in the inventory and adds no syntax or format detail beyond the schema; baseline 3 applies.

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?

Specific verb (delete) plus resource (skill), and it names the exact scope of the operation: the inventory plus the variants' skill groups and competencies. An agent can distinguish it immediately from set_skill and other siblings.

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 "use it only for mistakes" constraint, a named alternative (set_skill with level X) with the rationale (keeps gap reports honest), and a prerequisite (ask the person first). When-to-use, when-not-to-use and the alternative are all stated.

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

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

Annotations only declare the write/safety profile (readOnlyHint=false, destructiveHint=false), but the description adds the critical non-obvious trait that this is a whole-object replacement, not a merge ('It replaces the variant whole, so pass every field it should define'). It also discloses pre-save reference validation ('Every reference is checked before saving') and the return payload ('Returns `saved` and the `variant`'), which annotations cannot convey.

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?

Purpose is front-loaded in the first clause, followed by usage, replacement semantics, conditional requirements, validation, and return value in five tight sentences. Every sentence carries information an agent needs; no filler.

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 an 11-parameter mutation tool with no output schema, the description covers the risky parts: overwrite semantics, the inheritance/id-discovery workflow, conditional required fields, and the return keys. Combined with 100% schema coverage, an agent has enough to call it correctly without guessing.

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, but the description adds real semantics beyond it: conditional requirement logic ('A variant without `extends` needs `title` and `summary`') that the schema itself does not encode (only `id` is required there), plus the inheritance rule 'set only what differs'. It does not add format or ordering detail beyond the schema's own descriptions.

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+resource ('Create or replace a CV variant') and immediately defines the domain object as 'the plan for one kind of role (title, summary, which bullets and skills to show)'. An agent can distinguish it from list_variants and the set_*/upsert_* siblings without reading any 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 explicit when-to-use ('set up a variant or tailor one to a job post') and names the read alternative with an ordering instruction ('read the current ones with list_variants first'). It also points to where ids come from ('list_variants → `own` shows them'), leaving little to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description restates 'Read-only' rather than adding to it. However, it does disclose non-obvious behavior: results are ordered best-first, and the caller must extract keywords themselves in the post's own wording rather than being given them.

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?

Front-loads the purpose and the when-to-use rule, then pivots to keyword-extraction guidance and return shape. Dense and mostly earn-its-place, though the trailing 'Read-only' is redundant with the annotations.

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 no output schema, the description correctly covers the return value: `scores` with per-variant required and overall coverage plus per-keyword found/familiarity/missing status. Combined with the extraction and sequencing guidance, an agent has everything needed to call it correctly.

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 schema already documents lang, profile, keywords, variants, and preferred. The description's framing of `keywords` as required and `preferred` as nice-to-haves largely repeats the schema, so a baseline 3 is appropriate.

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 ('Measure how well each CV variant covers a job post's keywords') plus ranking behavior ('best first'). An agent can distinguish it from gap_report, which it names as the follow-up rather than the same operation.

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: use it first when a person shares a post to pick a variant, then call gap_report on that variant to see what is missing. It also names the alternative tool and the condition that selects it, leaving nothing to inference.

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

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

Annotations only mark it as a non-read, non-open-world write; the description adds the traits that matter: partial update (unspecified fields are preserved), a 'clear' sentinel for deleting optional values, whole-list replacement for `links`, and the return payload ('the `contact` as saved in profile.yaml') — valuable here since there is no output schema. The `links` replacement semantics go beyond, not against, destructiveHint=false, since it is a scoped setter for an explicitly whole-list field.

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 tight sentences, each doing distinct work: scope, boundary against siblings, mutation semantics, return value. The most decision-relevant facts (what it covers and what it does not) are front-loaded.

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 6-parameter, all-optional mutation with no output schema, the definition covers scope, partial-update behavior, value-removal syntax, list-replacement behavior, and the return shape. Nothing an agent needs to call it correctly 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 real meaning the schema lacks: the 'clear' sentinel for removing an optional field and the fact that `links` replaces rather than appends. It does not explain the `profile` resolution path beyond what the schema already says, so it stays short of a 5.

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 ('Update the person's contact details on the CV') and immediately scopes which fields belong to it (name, email, phone, location, links). It explicitly hands off roles and education to other tools, so an agent can distinguish it from upsert_role/upsert_education without opening any 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 both when-to-use (contact fields) and when-not (roles, education and the rest have their own tools), which is the routing decision an agent actually faces among 30+ siblings. It also states the partial-update contract ('Only the fields given change'), removing the main source of misuse.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/non-destructive profile is covered. The description adds the crucial overwrite semantics ('Each list you pass replaces the current one in full; leave a field out to keep it') and states the return value, which is real behavioral context an agent needs before calling. It stops short of noting validation failures or auth/profile-selection issues, so not 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?

Five tight sentences, front-loaded with the scope and the sibling exclusion before the replacement semantics. Every sentence carries distinct information — scope, alternative tools, overwrite behavior, classification rule, return value — with no padding.

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 four-parameter, all-optional mutation with no output schema, the definition covers what it touches, what it does not touch, how partial updates behave, the field-classification edge case, and what it returns. An agent has everything required to invoke it correctly.

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 schema already documents all four parameters, including the profile path default (--profile or HONEST_CV_PROFILE) and the per-language object shape. The description's only added semantic is the courses-vs-certifications rule, which is largely mirrored in the courses property description. Baseline 3 applies when the schema does the heavy lifting.

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?

Specific verb (replace/set) applied to three named resources (certifications, courses, spoken-languages) of the profile, and it explicitly names the sibling categories — roles, education, publications — that belong to other tools. An agent can route between set_profile_details and upsert_role/upsert_education/upsert_publication without opening any 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 when-to-use and when-not-to-use: 'Use it for those three lists only; roles, education and publications have their own tools.' It also supplies a disambiguation rule between two of its own fields ('A course or training without an exam goes in courses, never in certifications'), which is exactly the kind of guidance that prevents misfiling. Nothing 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.

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the description carries real extra weight: it discloses that level increases require evidence, that the server asks the person to confirm before saving, and that the call returns `saved` and `previous_level`. It does not cover permissions, failure modes, or how existing optional fields behave on a re-set, 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?

Three sentences, front-loaded with the core action, then sibling routing, then the behavioral rule and return values. No filler and nothing redundant with the schema.

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 an 8-parameter mutation tool with no output schema, the description supplies the missing pieces: sibling disambiguation, the evidence/confirmation rule, and the return payload. An agent has everything needed to invoke it correctly.

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 meaning the schema does not: it explains that evidence gates level raises and that a new skill is treated as rising from X, which clarifies the interaction between the `level` enum and `evidence` across parameters.

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 ('Add or change one skill in the inventory') and immediately delimits scope against two named siblings (set_skills, checklist_apply). An agent can distinguish this single-skill upsert from the batch tools without inspecting any 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 routing: use this for a single skill, set_skills for several at once, checklist_apply for a whole marked list. It also gives the conditional rule for evidence (required only when raising a level, including a brand-new skill) and notes that lowering is always permitted.

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

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

Annotations only say this is a non-read-only, non-destructive local write. The description adds real behavioral context beyond that: every upgrade requires evidence, upgrades are confirmed by the person in a form, a cap of 10 per call, only affirmative answers are persisted, and the exact result fields plus the follow-up call needed when some were never asked.

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?

Purpose and sibling routing are front-loaded, then constraints, then the return/continuation contract - a sensible order. The text is dense and the mid-sentence line break reads awkwardly, but no sentence is filler.

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?

No output schema exists, yet the description names the four return fields and prescribes the action for a non-empty upgrades_not_asked_yet, which is exactly what a caller needs to drive the loop. Nothing required to invoke or follow up 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, and the description still adds meaning the schema does not: the 10-upgrades-per-call limit, the human confirmation step, and that evidence is what gates a level increase. It does not restate per-field formats, which the schema already handles.

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 with scope ('Add or change several skills in one call') and immediately distinguishes itself from the singular sibling set_skill and from checklist_apply. An agent can select between the three without opening any 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 routing: 'Use set_skill for one skill and checklist_apply for a marked checklist,' plus a concrete continuation rule when upgrades_not_asked_yet is non-empty. Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations declare the mutation profile (not read-only, not destructive, not open-world), and the description goes beyond them by disclosing the upsert identity (institution+degree) and the return value. The one gap is that it doesn't state what happens when an existing match conflicts or that the entry is overwritten.

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 compact sentences: purpose+key, routing exclusion, then output. Front-loaded and every sentence earns its place with no filler.

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 5-parameter mutation tool with full schema coverage and no output schema, the description covers purpose, routing, and return. It would be complete at 5 with a note on overwrite/merge behavior when an entry already exists.

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 every parameter already carries its own docs including date formats and the bilingual degree shape. The description adds the honesty convention for the degree string, which is real added value, but the rest is schema territory. Baseline 3 with a small lift.

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?

Specific verb (add/change) and resource (education entry), plus the upsert key semantics ('the one with the same institution and degree'). It explicitly distinguishes scope from the sibling set_profile_details, so an agent can route without opening a 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 when-to-use ('degrees and formal studies') and an explicit exclusion routing courses/certifications to set_profile_details. Both the condition and the alternative are named.

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

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

Annotations already declare this is a non-destructive write (readOnlyHint=false, destructiveHint=false). The description adds genuine context beyond that: upsert semantics keyed on id (add-or-modify), the cross-variant publication behavior, and the return value. It stops short of stating permission/auth requirements, but adds real behavioral value.

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?

Front-loaded with the core action, then the routing guidance, then the variant aside and return value. Every sentence earns its place, though the variant clause is slightly dense in an otherwise tight definition.

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 mutation tool with no output schema, the description covers the add/modify branching, sibling routing, cross-variant behavior, and return value. Minor gaps (auth/permissions) remain but the essentials for correct invocation are present.

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 schema already documents all six parameters (id, url, year, title, venue, profile). The description reinforces that id drives the add-vs-change branch but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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 (upsert) and resource (publication/book/article/paper) and explicitly distinguishes itself from siblings by routing courses and certifications to set_profile_details. An agent can tell what this does and what it does not handle.

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 a concrete trigger ("when the person mentions something they published"), names the alternative for a confusable case (set_profile_details), and explains the save_variant interaction. Explicit when-to-use plus alternatives.

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

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

Annotations already declare write-non-destructive-closed-world, so the description is freed to add genuinely new traits: new roles require title/company/start (not captured by the schema, whose only required field is id), roles are kept in newest-first date order, and it returns the saved role. The 'Keep the person's real title' guidance is a useful quality constraint. It doesn't explain what happens to omitted fields on update, which is the main remaining gap.

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?

Front-loaded with the core verb+resource, then layers usage, required fields, ordering, and return in a compact paragraph. Every sentence carries information; the 'Keep the person's real title' sentence is slightly tangential but still actionable.

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 an 8-parameter upsert with no output schema, the description covers the essential extras: conditional required fields, ordering behavior, the bullet cross-reference, and the return shape. Only the partial-update semantics (what happens to unsupplied fields) are left implicit.

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 real meaning beyond the schema: it names title, company, and start as conditionally required for a new role even though the schema declares only id as required, and it reinforces the id-as-foreign-key relationship for bullets.

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+resource ('Add a job role, or change some fields of an existing one by its id') that is immediately distinguishable from siblings like upsert_education, upsert_publication, and remove_role. The upsert semantics and the id-based update path are both explicit.

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 a clear usage context ('while interviewing the person about their work history') and routes the related achievement data to the add_bullet sibling with an explicit pointer ('pointing to this id'). It lacks an explicit when-not (e.g., use remove_role to delete), so it stops short of full exclusion guidance.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description reinforces this with 'Read-only.' More usefully, with no output schema present, it discloses the return shape (ok, pages, checks with name/ok/detail, and text), which is genuine behavioral context beyond the 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?

Front-loads the purpose, then usage, then return values in three compact sentences with little waste. The enumerated check list is dense but each item earns its place by defining what ATS-safe means.

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 read-only inspection tool with no output schema, the description covers purpose, usage context, and the return structure, which is what an agent needs. It leaves some ambiguity about interpreting individual `checks` details, but that is a minor gap.

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 both `path` and `max_pages` are fully documented in the schema already. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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 (check) and resource (any PDF) with an explicit ATS-safety goal, enumerating the concrete checks: one column, no ligatures, dates on the role's line, text extractability, page count. It is clearly distinct from the many write-oriented sibling tools, and the build_cv reference anchors it in the workflow.

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 clear usage context: run it on a CV from any tool, and it notes that build_cv already runs it on the CVs it renders, which implicitly tells the agent when it is redundant. It stops short of an explicit exclusion statement, but the alternative and its condition are effectively named.

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