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

Annotations indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description goes beyond these by explaining that only provided fields are changed (partial update), that the block type cannot be changed, and crucially, it describes the response behavior: it returns the block as stored, with 'updated' listing only changed fields and 'ignored' revealing server-rejected fields. It also warns to check 'ignored' before confirming a change, and explains the only way to un-stage a block (phase:'always'). This is rich behavioral context that annotations don't cover.

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 a single, dense paragraph that is front-loaded with the primary purpose and partial-update semantics. It covers essential caveats (type change, response 'updated'/'ignored', phase:'always') without excessive fluff. It could be slightly more structured (e.g., bullet points) but remains readable and information-dense.

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?

Given the complexity (35 params, nested objects, enums) and the presence of an output schema, the description covers the key operational aspects: partial updates, immutability of block type, response interpretation, and the unique phase behavior. It also directs the user to get_mini_site for the blockId. However, it does not specify which parameters correspond to which block types (e.g., event vs product), but that may be inferable from schema names. The output schema exists, so return structure is covered. Overall, it is almost complete for an agent to call 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 0%, so the description must compensate for the 35 parameters. It does mention the broad categories of fields (link title, URL, price, event date, opening hours, display order) and specifically explains the 'phase' parameter in the context of 'always' clearing staging. However, it does not detail each of the 35 parameters, but given the large schema, the description provides a useful high-level summary and highlights the key parameter ('phase') with non-obvious behavior. This adds value beyond raw schema names.

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 clearly states it patches an existing block on a bio page and lists the types of fields that can be changed (link title, URL, price, etc.). It distinguishes from sibling add_mini_site_block and remove_mini_site_block by focusing on patching an existing block, but it does not explicitly name these siblings, so differentiation is implicit rather than explicit.

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?

The description provides explicit guidance on when to use this tool: it mentions using get_mini_site first to get the blockId, and states that the block type cannot be changed—if that's needed, remove and add a new one instead. It also gives a specific scenario for using phase:'always' to clear staging, which is a clear when-to-use instruction.

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