Place blocks on a page (declarative)

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

Annotations declare readOnlyHint:false, destructiveHint:false, idempotentHint:true. The description reinforces these honestly (no contradiction: dry_run writes nothing, replace doesn't destroy blocks, merge is repeatable) while adding genuinely new behavioral disclosure beyond annotations: auto-stack fallback, clipping when Σ(heights) exceeds budget, preservation of optimized geometry, and the overflow field in the response. It even warns about parallel-loop conflicts via expected_updated_at. No hidden surprises are left implicit.

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 description is dense and information-rich — it earns its length with concrete values (50% default, budget guide, step sizes of 25), and it front-loads the most important facts (atomicity, mode semantics) before the budget guide. It loses half a point for length: at 700+ words it's on the edge of what a description should hold, and a few items (e.g., the within-paragraph 're-read, re-apply, retry') could be trimmed without loss. Still, structure is excellent: every sentence adds information and the flow from purpose → modes → edge cases → budgets → fallback plan is logical.

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 tool this complex (7 params, 2 modes, atomic RMW, geometry placement, budget constraints, concurrency), the description is thorough: it covers failure modes (clipping), feedback (overflow in response), preview (dry_run), checked confirmation for destructive replace, and forward-migration guidance (raise grid height via update_resource). The schema's own text (descriptions on blocks, position, etc.) carries its weight, but the description doesn't rely on it — everything an agent needs to call place_blocks safely and effectively is within reach. Output-schema absence is not a gap here.

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 the schema already documents each parameter individually. The description adds meaningful cross-parameter interactions (position+height precedence rules, 'an entry with NEITHER position NOR height keeps an already-placed block's current geometry', auto-stack ordering) that give value beyond the schema. The grid-budget guidance (e.g., 'filter bar 8-10, KPI band 18-22, chart card 30-35, table 35-40') is excellent proactive guidance, though the schema already covers some of this, so this is a strong 4, not quite a 5 (which would be reserved for a tool whose schema did none of this).

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?

The description opens with a crisp verb+resource statement ('Declaratively manage which blocks a page (layout) shows, in ONE atomic read-modify-write') that immediately conveys both function and scope. It explicitly names its own boundaries with sibling guidance integrated inline: 'Blocks are placed, not created (create_block first) and never deleted (delete_resource does that).' An agent could select this tool without ambiguity among 40+ siblings.

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?

Every non-obvious behavior is scoped to exact mode semantics: merge = upsert/remove only; replace = page becomes EXACTLY the list (confirm:true required). The description also covers edge cases (preservation of grid.layouts, hidden flags, geometry of surviving blocks) and names the sibling tools that own related concerns (create_block, delete_resource, update_resource, dry_run preview). An agent could decide when to branch to mode=replace vs merge with no further help.

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