read_notes

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses budgetBytes truncation semantics (fair-share cut, truncated: true, noteBytes retained for continuation), per-item error isolation ('a failing item returns its own error without failing the batch'), and that contentHash is always the whole-file hash usable as prevHash. These are non-obvious behaviors an agent could not derive from the schema.

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 purpose, then batching rationale, then budget/truncation behavior, then error isolation and contentHash. Four dense sentences with no filler; each one carries information an agent needs.

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?

No output schema exists, yet the description compensates by describing the return contract (same fields as read_note, in request order, truncated flag, noteBytes, contentHash). Combined with rich budget/error semantics, an agent has everything needed to call it correctly and handle partial results.

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: the default value and unit of budgetBytes, its truncation behavior, and the cross-item semantics ('each item takes the same options as read_note'). It does not restate the per-field span options, which the schema already handles well.

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+resource with explicit batch scope: 'Read up to 20 notes (or spans of them) in one call instead of repeated read_note calls.' This immediately distinguishes it from the sibling read_note by cardinality and by naming the upstream tools whose output feeds it (search, query_notes, list_notes, get_backlinks).

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 when to use it (bulk-fetching top hits from search/query_notes/list_notes/get_backlinks) and routes the agent to the alternative for follow-up ('read the rest with read_note'). Both the when and the fallback path are stated, not inferred.

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