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

Annotations indicate non-destructive behavior (destructiveHint=false), and the description confirms notes accumulate without overwriting. It adds that notes are dated (timestamped) and placed in a specific section, going beyond annotations. However, it doesn't detail return behavior or error cases.

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 concise sentences: first states the action, second provides context on content and behavior. No wasted words, front-loaded with the core purpose.

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 tool with 2 parameters and no output schema, the description covers purpose, usage context, and behavioral traits (accumulation, dating). Given the sibling tools, this is sufficient for an agent to select and invoke 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?

The input schema already provides descriptions for both parameters ('id' and 'note'), achieving 100% coverage. The tool description repeats that notes accumulate (behavior) but adds no additional semantic detail about the parameters themselves (e.g., format, constraints beyond schema). 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?

The description clearly states the tool adds a dated note to the 'Notas de entrevista' section of an offer. It specifies the kind of content suitable for the note (interviewer, questions asked, feedback, anything to review before next round). This distinguishes it from siblings like update_skill_level 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?

The description explains that notes accumulate and never overwrite, which is a key usage behavior. It implicitly tells when to use (for interview-related notes) but does not explicitly compare to alternatives or specify when not to use. Still, it provides clear context for use.

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 description reveals side effects: removes from radar, adds to profile, discards the original offer. Annotations only provide idempotentHint=false and destructiveHint=false, but the description adds significant behavioral context not covered by annotations.

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

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

The description is two sentences, dense with information, front-loaded with the key concept, and every sentence adds value without redundancy.

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?

The description covers the tool's purpose, usage constraints, parameter nuances, and behavioral effects. It is fully sufficient for an agent to decide when and how to invoke 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?

With 100% schema coverage, the description still adds value: it explains that 'term' must match the radar exactly, that 'evidence' is a note and the offer is not preserved, and that 'category' is optional only if missing from radar.

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 clearly states the verb 'confirma' (confirms) and the resource 'skill', and explains that it moves a skill from the radar to the profile. It distinguishes itself as the ONLY path from gap to profile, differentiating it from 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 explicitly says to use only when the user confirms acquisition and never on own initiative. It does not name sibling tools as alternatives, but the context and the phrase 'UNICO camino' imply exclusivity.

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?

Beyond readOnlyHint annotation, description adds ordering logic and semantic urgency meaning, but doesn't disclose auth or other behaviors (though not needed for a simple read).

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 clear, front-loaded sentence with no wasted words. Perfectly concise for the tool's simplicity.

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

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

Given zero parameters and high schema coverage, description fully covers what the tool does. No gaps in understanding.

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?

No parameters, so baseline 4 applies. Description adds no param info since none exist.

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?

Description clearly states it returns all gaps sorted by counter descending, which is a specific verb-resource combination. It distinguishes from siblings like record_gap which are for writing.

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?

No explicit when/when-not guidance, but purpose is clear enough that an agent can infer usage. No mention of 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 readOnlyHint=true, indicating safe read operation. The description adds that it checks the alive status and data folder, providing context beyond the annotation. No contradictions.

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

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

The description is a single sentence that efficiently conveys the purpose. It is front-loaded with the action and resource, with no unnecessary words.

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

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

Given the tool has no parameters, no output schema, and a simple purpose, the description is fully complete. It tells the agent exactly what the tool does and what it returns (status and folder).

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 has no parameters, so the baseline is 4. The description doesn't need to add parameter meaning beyond what the schema provides (empty).

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 uses a specific verb ('comprueba' meaning checks) and identifies the resource (server aliveness and data folder). It clearly distinguishes from sibling tools (skills, offers, gaps) which are unrelated.

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 context implies this is a health check tool for verifying server status, which is clear. It doesn't explicitly state when not to use or list alternatives, but the purpose is straightforward.

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 description fully explains the tool's behavior beyond annotations. It specifies that the tool never duplicates, increments a counter and adds the source if the term exists, or creates it with counter 1 if new. This provides clear behavioral transparency. Annotations indicate it is not idempotent (idempotentHint: false) and not destructive (destructiveHint: false), and the description aligns with these traits.

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

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

The description is extremely concise: two sentences. The first sentence states the core action and behavior, and the second provides clear usage guidance. Every sentence adds value without 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?

Given the tool's simplicity (3 required parameters, no output schema), the description covers all necessary context: what the tool does, its behavioral details (upsert logic), and precise usage instructions. It is complete for an agent to understand when and how to invoke it.

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 all parameters are documented. The description adds value by providing concrete examples for each parameter (e.g., 'Kubernetes' for term, 'Google SWE II, Malaga' for source, 'Infraestructura' for category), which clarifies the expected format and granularity beyond the schema's brief 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?

The description clearly states the tool's purpose: recording that an offer asks for a missing skill. It uses specific verbs ('registra') and resources ('una oferta pide una skill que NO tengo'). It distinguishes itself from sibling tools like 'confirm_skill' (which likely confirms a skill) and 'list_gaps' (which lists gaps).

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 explicitly tells when to call the tool: once per missing skill per offer, including terms the user couldn't define. It does not explicitly state when not to use it or provide alternatives, but the context ('terminos que no sabria definir en una entrevista') implies it should be used for truly unknown skills. Sibling tool names like 'confirm_skill' and 'update_skill_level' suggest alternatives for existing skills, but this is not spelled out.

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 mark the tool as idempotent and non-destructive. The description adds useful context by specifying that only the analysis is replaced while status and notes are preserved. This goes beyond annotations and helps the agent understand what mutations occur.

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 with no wasted words. The main action is front-loaded, and the second sentence clarifies behavior. Perfectly concise.

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

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

Given 8 parameters and no output schema, the description covers the core behavior, idempotency, and preservation semantics. It lacks mention of return values or error cases, but for a save/update tool it is fairly complete.

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 documents all parameters. The description adds some context for the 'markdown' parameter (expects six-point template), but does not add value for other parameters. 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?

The description clearly states the tool creates or updates an offer file with its analysis, and explicitly distinguishes from siblings by stating that status and interview notes are preserved. The verb 'crea o actualiza' and resource 'archivo de una oferta con su analisis' are specific.

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 implies when to use the tool (to save/update analysis) and when not to (for status/notes updates, use sibling tools). However, it does not explicitly name alternative tools like 'set_offer_status' or 'add_offer_note', so the guidance is clear but not fully explicit.

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 idempotent and non-destructive. Description adds that changes are recorded with date, enriching the behavioral context without contradiction.

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 concise sentences: action+effect, cycle definition, lateral exits. No wasted words, well-structured and 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?

Given 2 params and no output schema, description adequately explains lifecycle and lateral moves. Could mention validation or error handling, but sufficient for typical use.

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 covers 100% with descriptions. The description adds lifecycle meaning to the status parameter beyond the enum list, providing useful context for the cycle order.

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 clearly states the tool moves an offer through its lifecycle and records the change. It specifies the cycle sequence and lateral exits, distinguishing it from siblings like save_offer.

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 as moving an offer status, but no explicit when-to-use vs alternatives or exclusions are given. Could mention that save_offer is for other modifications.

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 idempotent and non-destructive behavior. Description does not contradict and adds minimal additional context (the update action is obvious).

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 action, efficient and clear.

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?

Simple tool with only two params and no output schema. Description covers core purpose and usage context, though could mention what happens if term not found.

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. Description adds no extra meaning beyond what schema already provides for term and level.

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 clearly states it changes the level of a term already in perfil-skills.md, and distinguishes from confirm_skill for terms not yet in the profile.

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 provides when to use (terms already in profile) and alternative (use confirm_skill for new terms).

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