update_block_rich_text

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

Annotations already declare the write, destructive, idempotent, and open-world profile, so the safety semantics are covered structurally. The description adds the payload construction contract but says nothing about the destructive implication (that prior rich text on the block is replaced), permission requirements, or what happens with malformed JSON. That is adequate but not rich context above the annotations.

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?

Two sentences, front-loaded with the purpose and immediately followed by the one piece of information an agent cannot get from the schema. The inline example is compact and directly actionable; no sentence is wasted.

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?

An output schema exists, so return values need not be described, and annotations cover the mutation profile. What is missing is the replacement semantics and the distinction from the plain-text sibling; otherwise the description is sufficient for a two-parameter mutation to be invoked 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 coverage is 0%, so the description carries the burden, and it does compensate meaningfully for rich_text_json by specifying that it is a JSON array of rich text objects and giving a concrete example with type, text.content, and annotations.bold. block_id is left unelaborated, and the example shows only a single-element array with one annotation, leaving the fuller object shape to the agent's knowledge of the format.

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 names a specific verb and resource ("Update a block's rich text") and adds a scoping qualifier ("fully specified formatting") that hints at structured rich-text rather than plain text. It stops short of naming or contrasting with the close sibling update_block_text, so the agent must infer which of the two to pick for simple content.

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?

Usage is implied by "fully specified formatting" — the agent can infer this is for cases needing rich annotations rather than plain strings — but there is no explicit when-to-use, when-not-to-use, or alternates such as update_block_text or insert_text_after. The reader must derive the routing decision from the wording alone.

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