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

Annotations already cover the read-only, non-destructive profile, and the description adds real context beyond them: under API version 2026-11 writes return before they are searchable with index_state="pending", and query_workspace only sees indexed content. That consistency-model detail is exactly the kind of behavior an agent needs and cannot get from the annotations.

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?

It is short and front-loaded, but the telegraphic sentence fragments ("Indexing backlog.") and the parenthetical version note make it read like an internal note rather than an instruction. Nothing is padded, yet the terseness costs parseability.

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?

An output schema exists, so return values need not be explained, and the description supplies the key event/consistency context. Still, for a tool whose name promises 'status', the description never says what status is reported or what the namespace parameter does, leaving gaps an agent must guess at.

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?

There is one optional parameter, namespace, with 0% schema description coverage, and the description never mentions it or explains what scoping to a namespace does to the result. The only parameter-adjacent hint ("Read by key with dereference") describes a different tool, so the description does not compensate for the coverage gap.

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 the fragment "Indexing backlog," which gestures at the resource but never states a verb or says that the tool reports index/pending state. It does differentiate from siblings by naming query_workspace, dereference, and the DOC_INDEXED event, so the domain is inferable, but the actual operation remains vague.

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?

It implies when the tool matters (writes are not yet searchable, query_workspace won't see them) and points at two alternatives: "Read by key with dereference, or wait for the DOC_INDEXED event." However, it never says explicitly when to call get_index_status versus those alternatives, so routing requires inference.

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