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

Annotations already declare readOnly, idempotent, non-destructive, so the description correctly focuses elsewhere and adds real behavioral detail: the default response excludes document bodies, the full view is bounded and offset-paged, and archiving is opt-in. It stops short of stating response size limits, truncation behavior, or what the warnings/pending fields signify.

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?

Two sentences, front-loaded with the primary purpose and the returned payload before the view-mode variants. The first sentence carries a long enumeration of document fields and project-level metadata, which is dense but each item is informative; nothing is filler.

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 appropriately enumerates the returned fields, and it covers the read-only, default-safe profile the annotations promise. The one real hole is the offset/result_offset distinction for a 5-parameter tool with zero schema prose, which an agent could easily get wrong.

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 description coverage is 0%, so the description must carry parameter meaning: it explains view (index vs full), the existence of offset paging, and include_archive's effect. However, two similarly named integer parameters, offset and result_offset, are left ambiguous — neither is distinguished, and the description never says whether 'offset paging' refers to documents, bodies, or result windows.

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?

States a specific verb (Read) plus a precisely scoped resource (the index of one project) and enumerates exactly what comes back: documents with id, role, revision, load policy, size, outline and preview, plus contract_version, locks, warnings and pending state. The 'one project' scope plus the emphasis on index metadata cleanly separates it from read_document (single document) and list_projects (project enumeration).

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?

Frames it as 'the starting point of a session' and explains which mode to pick: the default view=index returns no bodies, view=full returns bounded bodies, include_archive adds archived documents. It never names an alternative tool for the cases this one doesn't cover (e.g., fetching a single document body via read_document, or locating documents via search_documents).

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