Edit Career Point

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

Annotations only say it is a non-read-only, destructive, idempotent, closed-world write. The description goes well beyond that by disclosing the workflow side effect: editing text regresses the point to DRAFT and removes it from the composed resume and career export until re-approval. That is exactly the consequence an agent must know 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?

Two sentences, zero filler. The action is front-loaded and the consequence statement follows immediately, with the exclusion clause last.

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 3-param mutation tool with no output schema, the description supplies the important missing piece (the draft regression). It omits what happens when both optional fields are null and whether any point state blocks editing, but nothing critical to a correct call 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?

Schema description coverage is 0%, so the description must carry parameter meaning, and it only names the two optional fields (text, tags) without explaining that null means 'leave unchanged', whether tags replaces or merges the existing set, or the point_id format. The field names align with the schema, so this is adequate but leaves real ambiguity.

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 pair and resource: 'Reword a Career KB point or retag it.' It also draws the boundary against sibling tools by declaring 'Cannot approve, retire or delete a point,' which separates it from kb_approve_points and the other kb_edit_* tools without needing to open their 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 clear context (text vs. tag edits) and names the follow-up route when approval is needed (kb_approve_points or /career). It does not spell out when to prefer kb_edit_point over kb_edit_entity/kb_edit_profile, but the resource noun makes that inference safe.

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