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

With no annotations provided, the description carries the full burden. It discloses paging behavior (footer shows count and offset), threading via post id, and inheritance semantics. It doesn't explicitly state it's non-mutating, but the verb 'read' implies that, and no side effects are mentioned. For a read operation, this is adequate transparency; a 4 reflects that it goes beyond the schema but doesn't explicitly address non-mutation.

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 dense paragraph, but every clause earns its place given the 11-parameter complexity. It front-loads the core purpose and then layers usage modes and paging details. While long, it's efficiently structured; a 4 reflects that it could benefit from bullet points but remains readable and non-redundant.

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?

For a tool with 11 parameters and multiple modes, the description covers all necessary operational aspects: what a board contains, inheritance rules, paging, thread reading, global request views, share handling, and token override. Even without an output schema, it describes the footer and the kinds of posts returned. Nothing an agent needs to call it correctly is missing.

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%, but the description adds significant semantic value: it explains how parameters interact (e.g., 'Pass post to read one thread in full'), when to omit them (global requests), and how offset relates to the footer. It also clarifies the 'requests' enum and share context. This goes far beyond the schema's one-line definitions, making the tool genuinely easier to use correctly.

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 a clear verb and resource ('Read the board on a folder or document') and enumerates the specific content types (context, requests, inconsistencies, working). It also distinguishes itself from sibling read tools by noting that other tools show only a short trailer, positioning this as the full-board reader. This differentiates it effectively.

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 gives explicit guidance on when to use this tool vs alternatives: 'read_org_doc, list_org_docs and the write tools already show a short board trailer — call this when you want the whole of it.' It also explains multiple usage modes (post to read a thread, no arguments for global requests, requests='asked_by_me' for own requests) with clear conditions. No ambiguity about when to invoke.

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