List children of a block

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

The description indicates a read-only operation ('List') and immediate children, but with no annotations provided, it misses details like error handling, rate limits, or pagination behavior (default page size, cursor format). The description is adequate but not fully transparent.

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 sentence with a clear recommendation, front-loading the core purpose. No unnecessary words or repetition.

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?

The description covers the basic purpose and a usage scenario, but lacks details on pagination mechanics, response format (no output schema), and how to interpret the start_cursor. For a simple list tool, it is minimally complete.

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?

Only the block_id parameter has a schema description ('Buildin object ID (UUID-like).'), and the tool description does not add meaning for page_size or start_cursor. With 33% schema coverage, the description fails to compensate, leaving users to guess parameter usage.

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 the action ('List immediate children'), the resource ('block (or page)'), and includes pagination. However, it does not differentiate from the sibling tool 'buildin_get_page_children', which may cause confusion about which to use for page children.

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 advises using this tool instead of scraping, providing a clear alternative. But it lacks guidance on when to use this versus sibling tools like buildin_get_block_children vs buildin_get_page_children, and no mention of prerequisites or limitations.

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