Append Block Children

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

Annotations already indicate a write operation (readOnlyHint=false). The description adds that it requires insert content capabilities (permission hint) and mentions the position object for insertion control. No disclosure of rate limits, error behavior, or side effects beyond the schema. With limited annotation coverage, more behavioral context would be beneficial.

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-loading the core action. Each sentence serves a purpose: defining the operation and noting the optional positioning. No unnecessary words. Ideal length for quick comprehension.

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 of the tool (nested objects, many block types) and no output schema, the description does not explain return values or how to construct the children array. The schema fills this gap, but the description could summarize the block structure or note common pitfalls. However, the schema is comprehensive and present, so the tool is still usable with effort.

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 100%, so the schema already documents all parameters in detail. The description adds value specifically for the 'position' parameter by summarizing its usage (start, end, after a block). For other parameters (block_id, children), no additional meaning is provided. Overall, the description complements the schema but does not significantly enhance semantic understanding.

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?

Clearly states the action (append), resource (new children blocks to a parent block), and context (in Notion). The mention of 'insert content capabilities' adds a permission note. However, it does not differentiate from sibling tools like notion_append_content or notion_append_markdown, which serve similar purposes with different content formats.

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?

Provides a prerequisite ('Requires insert content capabilities') and hints at usage of the optional 'position' object. However, no explicit guidance on when to prefer this tool over alternatives (e.g., notion_append_content, notion_update_block). The agent would need to infer based on the schema of children blocks.

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