roam_fetch_block

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

Annotations already mark this as read-only and idempotent, and the description aligns with that by stating it 'fetches' and 'returns' data. It adds valuable behavioral context beyond the annotations: the graph's conventions can change read semantics, and the response includes a specific ancestors array shape when requested.

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 two short paragraphs with no filler. The first sentence states the core function and return values, and the second conveys an essential prerequisite in an 'IMPORTANT' callout. Every sentence earns its place and the structure is immediately scannable.

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?

With no output schema, the description compensates by naming the exact return fields. The mandatory prerequisite for roam_get_guidelines is highlighted, and all parameters are covered by the schema. For a read-only fetch tool with clear sibling context, this is fully adequate.

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 parameter descriptions already document depth, graph, block_uid, write_key, and include_ancestors. The description adds minimal extra semantic value beyond restating those concepts in prose (e.g., 'children down to a specified depth' maps to depth), but it does not introduce information absent from the schema.

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 begins with a specific verb and resource: 'Fetch a block by its UID' with optional children and ancestors, which clearly distinguishes it from page-level fetch siblings like roam_fetch_page_by_title and roam_fetch_page_full_view. It also enumerates the return fields, reinforcing what the tool does.

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 explicitly instructs the agent to call roam_get_guidelines once per session before using the tool, including for reads, and explains that conventions affect how results are read. It does not explicitly name alternative tools or provide exclusion criteria, but the prerequisite and context are clear.

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