add_language_skill

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

No annotations are provided, so the description must disclose side effects and constraints. It only says 'Add'—implying mutation—but does not mention whether it modifies the draft, if it is idempotent, if overwriting occurs, or what happens on conflict. There is no note about auth, rate limits, or failure modes, leaving a significant transparency gap for a write operation.

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 three compact sentences with no filler. It is front-loaded with the core purpose, then adds the 'separately' rule and a lookup tip. Slight room to improve by mentioning the draft_id parameter, but overall it is efficiently structured and to the point.

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 no annotations and an output schema that presumably describes the return, the description covers the main usage rules (single language per call, mother tongue handling, code lookup). However, it omits any behavioral expectations such as result handling, error cases, or safety implications, which are important for a mutating tool. The schema fills parameter semantics well, but the description could be more transparent about side effects.

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 schema already gives thorough descriptions for both `draft_id` and the nested `skill` object (including the CEFR level explanation and `mother_tongue` semantics). The description adds the practical hint to look up language codes and emphasizes 'mother tongues included', which is useful but overlaps with the schema's note. It does not decode the nested structure further, so it adds only marginal value beyond 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?

The description clearly states the action ('Add one language') and the resource (the person's language skill). It also explicitly notes the one-at-a-time behavior ('Add every language separately') and points to a sibling tool (`lookup_language`) for code resolution, distinguishing it from other add-type siblings like `add_work_experience` or `add_digital_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 direct usage rules: add each language in its own call, include mother tongues, and verify language codes via `lookup_language`. This effectively tells an agent when to invoke this tool and how to prepare parameters, though it doesn't explicitly mention alternatives; the context is sufficient to select this over sibling add-tools.

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