roam_get_subpages

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

With annotations already declaring read-only/idempotent, the description adds meaningful behavioral details: it explains that the trailing slash is added automatically, that filter_tag matches both #tag and [[tag]] usage, and that include_content controls whether full block content is returned. The IMPORTANT note about conventions affecting how results are read adds extra context beyond 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?

The description is three sentences plus a focused IMPORTANT note. It front-loads the core purpose, uses no filler, and each sentence adds a distinct piece of information.

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 tool's behavior, prerequisites, and optional parameters. Since there is no output schema, it would be helpful to state the exact return shape, but the description implies a list of sub-pages and mentions content inclusion for include_content. Overall it's sufficiently complete for a read-only list tool.

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 input schema covers all 5 parameters with detailed descriptions, so the baseline is 3. The description enhances the meaning of 'prefix' by explaining the namespace/title-prefix matching convention and the hierarchy section, which aids correct parameter use.

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 opens with 'Fetch all sub-pages (namespace children) of a given page prefix,' which is a specific verb+resource. It further distinguishes itself from roam_search_hierarchy (block parent/child traversal) and clarifies the title-prefix matching rule.

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?

Explicitly names an alternative tool: 'distinct from roam_search_hierarchy which traverses block parent/child relationships.' It also mandates a prerequisite: 'call roam_get_guidelines for this graph once per session before using this tool,' including for reads.

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