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

Annotations only supply destructiveHint=true and a title, so the description carries most of the load — and it does, disclosing that the operation is additive and non-idempotent (each call appends a new note). It does not explain why the operation is flagged destructive or whether notes can be duplicated/removed, leaving one gap against the annotation.

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, front-loaded clauses starting with 'WRITE:' so the operation type is immediately visible. The raw endpoint is mildly redundant but cheap, and nothing is padded.

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 the essentials: write semantics, non-idempotency, and authorization scope. Minor omissions (visibility of the note to other users, duplicate handling at the API level) are low-risk 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 coverage is 100% with both parameters documented (candidate_id as numeric id, content with length bounds), so the schema does the heavy lifting. The description only restates that a single candidate and text note are involved, adding no format or length guidance of its own.

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 a text note to one candidate's activity history' — plus the underlying endpoint. This clearly separates it from read-side siblings like traffit_get_candidate_activities, which an agent might otherwise pick for note-related work.

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 ('Scope: employee', one candidate per call) and an explicit safety rule: 'do not repeat a call that succeeded.' It stops short of naming the read alternative for inspecting existing notes, so routing guidance is strong but not exhaustive.

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