lib_footprint_update_document_source

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

Goes well beyond the destructiveHint=true annotation: states it is IRREVERSIBLE, that no undo and no backup snapshot exist because library assets aren't documents, spells out the required library permission level, and declares the boolean return. This is exactly the extra context the annotation bar rewards.

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 irreversible warning first, then workflow, then precondition, then return value - well ordered. It is somewhat dense with parentheticals, but every sentence carries load; 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?

A destructive mutation with no output schema, yet the description covers safety, required permissions, a safe pre-step, and the return type. Nothing an agent needs to call it correctly 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 coverage is 100%, so the baseline is 3. The description adds real meaning for libraryUuid (must be a library you can write to - personal/team/project) and ties documentSource to the format document_get_source returns, which is slightly beyond the schema text.

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?

Precise verb+resource: 'Replace a library footprint's entire source.' The 'entire source' scope and the 'footprint' (vs the symbol sibling lib_symbol_update_document_source, and vs document_set_source on the open document) let an agent distinguish it without opening a 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?

Gives a clear precondition workflow ('Read and save the current source first' via lib_footprint_open_in_editor + document_save_to_file) and a gating condition ('must live in a library you can write to'). It does not state explicit when-not-to-use or name the update-in-place sibling as an alternative, so it stops short of a 5.

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