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

Annotations already cover the read-only/idempotent profile, and the description still adds real behavior: text is paged, max_chars caps at 20000, total_chars reports full length, and document text is untrusted reference data rather than instructions. It doesn't mention auth requirements or how workspace scoping affects visibility.

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?

Three compact sentences, front-loaded with what is read and how paging works, followed by a safety note. The trailing 'Read-only.' is redundant with readOnlyHint=true, a small but real waste.

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 supplies the return-shape essentials (one text page, next_offset, total_chars) and the injection caution. It omits whether document metadata is returned alongside the text and does not clarify that workspace_id is optional for reads, despite the schema prose implying it.

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?

With 67% schema coverage the baseline is 3, but the description adds chaining semantics the schema lacks: the offset/next_offset round trip, the 20000 cap on max_chars, and total_chars as the length signal. brand_id and the free-form query object remain undocumented in both places.

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 and resource: 'Read a workspace Brain document and one page of its extracted text.' The paging detail distinguishes it from a plain document fetch, but the description never names the closely related siblings (aidelly_get_brain_entry, aidelly_get_brain_context, aidelly_search_brain), so the agent must infer the boundary.

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 explicit in-call guidance for pagination ('pass next_offset as offset for the next page') but no when-to-use/when-not guidance relative to alternatives. Nothing tells the agent when to reach for this versus aidelly_search_brain or aidelly_get_brain_context.

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