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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds the semantics behind that: it is a partial patch, unreferenced fields and all other blocks are untouched, and 'A block keeps its type' is a constraint not present in the schema. It does not explain what a destructive outcome looks like in practice (e.g. field removal) or what comes back from the call, but the added context is meaningful.

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 key behavior — partial update by block id — is front-loaded in the first clause, and the two follow-on sentences each carry a distinct fact (type immutability, wiki footer vs articles). The opening sentence is long and slightly run-on, but there is 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?

For a destructive, idempotent mutation with a nested 'fields' object and no output schema, the description covers the semantics an agent needs: partial replacement, type preservation, and the wiki split. Missing only secondary detail such as failure behavior or whether the updated block is returned; annotations already cover the safety profile.

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 id, path, token, fields and summary are already documented, including null-removes-a-field and whole-array replacement. The description largely restates that ('by its id from read_page', footer handling) rather than adding syntax or format detail. Baseline 3 is appropriate when the schema carries the load.

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 ('Change some fields of one block on a page') and immediately bounds the scope: only the named fields change, everything else stays. It also pins the id's provenance to read_page and distinguishes its behavior from save_wiki_page, so an agent can separate it from insert_block, remove_block, move_block and whole-page writes 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 concrete routing: get the id from read_page, and on a wiki use the block tools for the footer but save_wiki_page for articles. That is real when-to-use-an-alternative guidance. It stops short of a full exclusion list (e.g. when to prefer write_site for whole-page rewrites), so it is clear context rather than a complete decision matrix.

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