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

Annotations already declare readOnlyHint=true, and the description is consistent, adding real context: the source is 'CURRENT', it includes a hash used for optimistic concurrency (expectedHash), and editing must keep data-ui-id stable. It does not cover auth/rate-limit concerns, but the read-only nature plus the workflow detail is solid beyond 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?

Front-loaded with the purpose and return payload, followed by the editing guidance and contract rules. Dense but every clause earns its place; slightly jargon-heavy with tokenisation/hash references but still efficient.

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?

Since an output schema exists, return values need not be explained, yet the description helpfully summarizes them anyway. It also supplies the workflow (edit minimally, submit only changes) and the required contract read, leaving little for an agent to infer about how to call it correctly.

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 uuid/blockId are already fully documented in the schema. The description mentions `edits` and expectedHash, but those belong to submit-version, not this tool's parameters, so it adds little parameter meaning. Baseline 3 is appropriate.

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 precise verb+resource ('Read one block's CURRENT source') and enumerates exactly what is returned (tokenised file bodies, registered name, shorthand attributes, backgroundColor, skills, description, tags, hash). It also names a related tool (get-skill-doc) so an agent can separate the source-read from the contract-read. This is far more specific than a sibling like list-blocks.

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?

Clear usage context: read the current source in order to update it, then edit minimally and submit-version only changes. It also directs the agent to read the relevant block-contract via get-skill-doc before the first call. No explicit 'when not to use', so 4 rather than 5.

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