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

Beyond the annotations, the description discloses key behavioral details: the server generates the block id, edits to published pages only create an unpublished revision, and the response includes nextSteps hints that should be shared with the user. It also clarifies publish/unpublish sequencing, which is critical for an agent to avoid unintended live-page changes.

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 long but information-dense and mostly front-loads the core action before moving to workflow constraints. There is some redundancy around publish/unpublish waiting behavior, and the 13-vs-14 type-count error adds avoidable confusion, but most sentences contribute meaningful operational guidance.

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 complex tool with a large oneOf schema, the description covers the behavioral contract very well: draft-only saves, server-generated ids, nextSteps, and publish sequencing. However, it omits the save_contact variant entirely, miscounts the allowed types, and leaves editToken's purpose undefined, which are notable gaps given the schema's size and the need for precise invocation.

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?

The description adds useful meaning for the block parameter by emphasizing strict per-type props and server-generated ids, but it does not explain pageId or editToken, and with only 33% schema description coverage those unexplained parameters remain a gap. The schema itself carries most of the per-variant detail, so the description adds moderate value but does not fully compensate.

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 a specific action and resource: append a new content block to a link-in-bio page, which distinguishes it from block_delete, block_update, and block_reorder. It also enumerates the allowed block types, though the count is inaccurate—it says 13 while the schema defines 14 types including save_contact.

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 gives unusually explicit when-to-use guidance: for already-published pages it only saves an unpublished latest revision, and it instructs the agent not to call page_publish in the same turn, to wait for explicit user confirmation before publishing, and not to call page_unpublish unilaterally. This provides strong operational guardrails that go well beyond the schema.

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