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

Annotations only declare idempotentHint=false and destructiveHint=false; the description adds a meaningful behavioral fact not derivable from them - notes accumulate and are never overwritten - which reassures the agent that repeated calls append rather than replace. It also implies the timestamp is applied server-side ('dated note'). It stops short of saying what is returned, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and target are front-loaded in the first clause, and the second sentence about accumulation is short and earns its place. The middle content list is slightly padded but still useful guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter append tool with no output schema, the description covers what is created, where it goes, and the append-only behavior, which is most of what an agent needs. It omits any mention of permissions or the response shape, but neither is critical to invoking 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% with only two required parameters (id, note), so the schema already documents both; the description adds the fact that the note becomes 'dated' and lives in a specific section. That is minor added meaning beyond the schema, so the baseline of 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 (adds), resource (note), and target (the 'Interview notes' section of an offer) in one clause, plus the note's expected content. No sibling tool in the list adds notes, so the agent can identify this tool unambiguously.

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?

The description gives content guidance ('who interviewed the user, what they asked, feedback received') which implies when this tool is appropriate, but it never states an explicit when-to-use condition or names an alternative among siblings such as save_offer or record_gap. Usage must be inferred from the content examples.

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 cover idempotentHint=false and destructiveHint=false, so the description carries real weight: it discloses the mutation of two files, what gets written, and notably what gets dropped (the offer that created the gap is NOT kept). This is exactly the side-effect context a mutation tool needs beyond its 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?

Three sentences, front-loaded with the action and its effects, then the precondition. No filler; every clause 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?

With no output schema needed and full param documentation in the schema, the description supplies everything else an agent requires: precondition, side effects, and the exclusivity of this workflow path.

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 term, level, category and evidence are already documented with format and enum meaning in the schema. The description only echoes 'level and evidence' and adds no syntax or format detail beyond that — 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 ('confirms the user now has a skill that was in the radar') and names the concrete side effects (removes from gaps.md, adds to skills.md). This clearly distinguishes it from siblings like record_gap and update_skill_level.

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 ('only when the user confirms they have acquired it via certification, project or real experience'), explicit when-not ('never on your own initiative'), and states it is the ONLY path from gap to profile. 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?

readOnlyHint=true already establishes this is a safe read, so the description only needs to add context. It does: the result is exhaustive ('every gap'), ordered by count descending, and the ordering carries meaning about urgency. It does not describe pagination behavior or the fields of a gap record.

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?

A single sentence with the operation and its ordering rule front-loaded, followed by a short interpretive clause. There is no filler and nothing is buried.

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-argument read-only listing tool this covers what an agent needs to select and call it. The only omission is the shape of a returned gap entry, which is a minor gap given there is no output schema.

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?

The tool takes zero parameters, so the schema is trivially fully covered and the baseline of 4 applies. Nothing about parameter meaning is left unclear because there is nothing to parametrize.

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 ('Returns every gap in the radar') and adds the ordering rule, so an agent immediately knows this is the enumeration counterpart to record_gap. It never names a sibling explicitly, so it stops short of the 5 criterion for sibling differentiation, but the intent is unambiguous.

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?

The clause 'the top entries are what most offers have asked for, and therefore the most urgent to learn' implies the tool is for prioritization, but there is no explicit when-to-use, when-not, or named alternative. Usage is inferred rather than 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?

readOnlyHint=true is consistent with a health probe, and the description adds real value beyond the annotation by disclosing the second piece of information returned (the active data folder), which lets an agent use it as a configuration check, not just a liveness check.

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 short sentence, front-loaded with the primary behavior and appending only the secondary return detail. 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 no-param, no-output-schema tool the description is sufficient: it covers both the liveness result and the data-folder result, which is the entirety of what a caller needs. Minor omissions such as version or latency reporting are not required here.

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?

There are zero parameters, so the schema carries no burden and the baseline is 4; nothing in the description is needed to explain inputs.

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 (checks), the resource (server), and even an extra facet of the result (which data folder it is working on). It is trivially distinguishable from the domain siblings, though it doesn't need to differentiate itself from any of them.

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?

Usage is implied — an agent would call this to verify connectivity or diagnose availability — but the description never says when to reach for it (startup, before a batch, after a failure) or that it is the only liveness probe available.

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 idempotentHint=false and destructiveHint=false; the description adds the meaningful part by explaining the upsert semantics -- count increments and source is appended if the term exists, otherwise it is created with count 1 -- and that duplicates are never produced. It does not cover permissions, the response shape, or how the added source affects the existing entry, but the mutation consequences are well disclosed and consistent with the non-idempotent hint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and mutation behavior are front-loaded in the first three sentences, with usage rules following. Five sentences is on the long side for a three-parameter tool, and 'It never duplicates' partially overlaps with the later 'Never call it for something already in skills.md', but every sentence still carries actionable 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 mutation tool with no output schema and only partial annotation coverage (idempotency/destructiveness), the description supplies the core context an agent needs: the missing-skill scope, the create-vs-increment behavior, and the exclusion for skills already in the profile. Remaining gaps -- return value and any auth/permission requirement -- are minor for this operation.

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 term, source, and category are all already documented with examples in the schema. The description only implicitly reinforces what 'source' does (it is added to an existing entry), adding no format, naming, or placement detail beyond the schema. Baseline 3 applies when the schema carries the parameter burden.

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 opens with a precise verb+resource+condition: it records that a job offer asks for a skill the user does NOT have. It also discloses the underlying data behavior (radar entry incremented vs. created with count 1), which distinguishes it clearly from siblings like list_gaps or confirm_skill.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use ('call it once per skill the offer asks for that is missing from the user's profile, including terms the user could not define in an interview') and an explicit when-not ('Never call it for something already in skills.md'). However, it never names the alternative sibling tools an agent should route to for already-known skills (e.g. confirm_skill or update_skill_level), so the exclusion lacks a destination.

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?

Adds substantial behavior beyond the idempotentHint/destructiveHint annotations: content provenance (everything must already exist in profile/cv-data.json), an all-or-nothing failure mode when citing a missing id or tag, and the free-text boundary limited to headline/summary/location. It does not explicitly state that it overwrites an existing output/cv-<id>.html file, which is the main destructive consequence implied by destructiveHint=true.

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 write action and output path, then layers constraints and the do-not-auto-call rule. Dense but every sentence carries a rule; slightly long-winded in the projects paragraph where the schema already repeats the trim-before-drop guidance.

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, and the description covers the return artifact (file path, invisible stored comment), the validation failure mode, and the invocation workflow. An agent has everything needed to call it correctly and safely.

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% (baseline 3), but the description adds real meaning: which fields accept free text versus must reference existing ids, the omit-to-keep-unchanged convention, and the rationale that projects is where tailoring pays off most. That goes beyond the schema's own property 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 and artifact ('Writes output/cv-<id>.html, a version of the CV tailored to one offer') and immediately scopes it to selecting projects, lines, bullets and tags. No sibling (record_gap, save_offer, list_gaps, etc.) operates on CV rendering, so the distinction is unambiguous.

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 states when NOT to call it ('Do NOT call it on your own after an analysis: propose the tailoring and wait for the user to ask for it') and gives a fallback ordering rule ('trim lines inside each project before dropping a whole project'). This is a clear workflow constraint an agent would otherwise violate.

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?

The annotations already declare idempotentHint=true and destructiveHint=false, and the description meaningfully extends that by spelling out the upsert behavior and exactly what survives an overwrite (status and interview notes). It does not cover permissions, file location, or what happens to url/tags/score/salary on update.

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?

Two tight sentences with the create-or-update behavior front-loaded and the preservation rule immediately after. No filler, and the most decision-relevant fact (only the analysis is replaced) is stated early.

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 and 8 parameters, the description covers the central upsert risk well but leaves a real ambiguity: it says ONLY the analysis is replaced, yet the schema accepts url, tags, score, and salary, so an agent cannot tell whether those are updated or ignored on the update path. That gap matters for correct invocation.

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 eight parameters are already documented in the schema with formats and examples. The description adds no parameter-level detail beyond calling the markdown payload 'the analysis', which is the baseline expectation 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+resource ('Creates or updates an offer file with its analysis') and immediately pins down the upsert semantics. It implicitly separates itself from set_offer_status and add_offer_note by stating that status and interview notes are preserved, though it never names those 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?

The description tells you what the tool does on both the create and update paths, but gives no explicit when-to-use guidance, no prerequisites, and no routing to alternatives such as add_offer_note or set_offer_status for the fields it deliberately preserves. Usage is only implied.

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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the operation writes a dated log entry and follows a fixed lifecycle with terminal side exits, which matters when reasoning about state changes. It stops short of stating what happens on an invalid transition or whether exits are reversible.

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?

Two sentences, front-loaded with the core action before the lifecycle detail. Every clause carries information (action, log side effect, transition order, exit semantics) 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 only two well-documented parameters, no output schema, and annotations covering safety, the description supplies the one thing the schema cannot: the lifecycle semantics needed to pick a valid status. It leaves open edge behavior such as invalid transitions or reversibility of 'rejected'/'discarded', which is a minor gap for this tool's complexity.

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 enum is already enumerated, so the baseline is 3. The description goes further by giving the enum values meaning — the progression analyzed -> applied -> interview -> offer -> accepted, plus the two exit states and which of them is company-driven vs user-driven — context the bare enum list does not convey.

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 — moving an offer along its lifecycle and logging the change — and then enumerates the exact state machine, which distinguishes it from siblings like save_offer (creation) and add_offer_note (annotation). An agent can tell what this tool 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?

Usage is implied rather than stated: describing the lifecycle and the two side exits ('rejected', 'discarded') tells the agent which statuses are legitimate, but there is no explicit when-to-use or when-not-to-use guidance relative to save_offer or add_offer_note. The transition model is helpful context but not routing advice.

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 idempotentHint=true and destructiveHint=false, so safety and repeatability are covered structurally. The description adds the important precondition that the term must already exist, which is behavioral context beyond the annotations, though it stops short of saying what happens if the term is absent.

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?

Two short sentences, front-loaded with the core action and the key precondition, with the routing alternative second. Every clause carries information; 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 simple two-parameter mutation with no output schema and annotations already covering idempotency and non-destructiveness, the description supplies the precondition and sibling routing an agent needs. Nothing essential 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 (term, level) are already fully documented, including the enum values. The description reinforces that the term must already exist but adds no syntax or format 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?

The description states a specific verb (changes) and resource (level of a term in skills.md), and explicitly distinguishes itself from the sibling confirm_skill. An agent can tell immediately that this mutates an existing entry rather than creating one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit when: the term is ALREADY in skills.md. It also gives an explicit when-not with the named alternative: 'For something that is not in the profile yet, use confirm_skill.' 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.