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

Beyond the readOnlyHint annotation, the description discloses significant behavioral nuances: that the default full tree can be large, that status=archived returns a flat list rather than a tree, and that types returns lightweight summaries with empty children arrays and deliberately does not hydrate heavy content. It also warns about the platform's change-request model and treats content as data, adding safety-relevant context that the annotations do not convey.

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 dense, with front-loaded purpose and near-zero filler. The inclusion of the HTTP endpoint is useful, and the historical note about replacing legacy endpoints adds context. The final sentences about Busabase writes and treating content as data are tangential to this read-only tool but still relevant platform-level guidance; a slightly tighter focus would make it a 5.

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 present, the description carries a heavy responsibility and meets it. It explains all parameters' effects on response shape, mentions the NodeVO.hasChildren marker, clarifies the lightweight nature of the type list, and provides the prerequisite auth_verify flow for multi-space accounts. An agent has enough to invoke the tool correctly in all its modes.

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?

Although the input schema already covers all parameters with descriptions, the MCP description enriches the schema by explaining how parentId and depth interact (e.g., explicit parentId returns children directly for lazy expansion) and how types changes the response shape. It also clarifies that status=active walks the tree while status=archived returns a flat list, which is not fully evident from the schema alone.

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 'List nodes' and specifies the two output modes: the workspace tree and a flat summary list by type. It names the resource and the action precisely, and differentiates from siblings by stating that it replaces legacy GET /docs, /files, /folders, and /file-trees, and by pointing to GET /nodes/{nodeId} for opening a single item. This makes the tool's purpose unambiguous and distinct from related tools.

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 clearly explains when to use each mode: no parentId/depth returns the full tree, parentId/depth triggers depth-bounded fetch, and types returns a flat list. It also instructs multi-space accounts to call auth_verify first and specify targetSpaceIdmm, and it directs users to GET /nodes/{nodeId} for individual node detail. It does not explicitly contrast against siblings like nodes_search_by_name or list_archived, but the provided guidance is sufficient for most selection decisions.

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