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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds substantial context on top: the revision=value on the [[document]] line is meant to be passed as baseRevision so a later write is refused on conflict, incoming cross-document links are returned as a second grouped block, and a bounded read only returns links into the rows it covers. It also discloses empty-range behavior ('says so and gives the row orders the document spans').

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?

Front-loaded with the core action, and nearly every sentence carries load-bearing detail about modes, revision handling, or link output. It is dense and contains long parenthetical sentences (the outline enumeration, the revision sentence) that could be broken up for easier parsing, but there is little outright 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?

There is no output schema, so the description must carry return-shape information — and it does: meta.revision, outline contents (headings, titlePageHeadings, landmarks, item counts, references with referenceId), and the TrMD block format with [[row N]] anchors and ID-grid structure. For a read tool of this complexity, an agent has everything needed to call it and interpret the result.

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 baseline is 3, but the description adds real meaning beyond the schema strings: it defines what outline vs full actually return, states outline is the default, and clarifies that fromOrder/toOrder take 'row orders from the outline or a prior read'. That is operational semantics the schema's terse 'First row order to include' does not convey.

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?

Opens with a concrete verb+resource ('Read a document or a template') and immediately characterizes the two modes, so an agent knows this is the document reader. It does not explicitly contrast itself with sibling readers like traceable_board_read, traceable_test_plan_read, or traceable_library_read, leaving that distinction to inference from the resource name.

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?

Gives real routing guidance: outline is 'cheap; default when exploring', full is for content, and a full read should be bounded with fromOrder/toOrder 'to load only a section'. It also states a concrete precondition/alternative — accept a template id from traceable_workspace_templates to inspect a body before cloning with traceable_doc_create. It stops short of saying when NOT to use this tool versus other read siblings.

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