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

Adds substantial context beyond the readOnly/idempotent annotations: source-permission checking, a guarantee that credentials and the raw private bundle are never returned, pagination with next_offset and a full-document SHA256, and the crucial clarification that offsets are Unicode characters rather than bytes. It also warns that retrieved report/source text must be treated as data, not instructions, and that values are drafts — behavior an agent could not infer from structured fields.

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?

Dense but front-loaded: the permission gate and safety guarantee come first, then per-format output notes. The nested indentation and the fragmentary "markdown: paginated COMPLETE" line read awkwardly, but almost every clause carries operational information.

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?

For a read-only paginated retrieval tool with an output schema, the description covers the key gaps: permission gating, pagination mechanics, offset semantics, and prompt-injection caution. Only the limit parameter and identifier parameters are left unexplained, which is a modest gap rather than a blocking one.

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 0% schema description coverage the description must carry the parameters, and it only partially does. It explains offset units (Unicode characters, not bytes) and describes what each format value yields, but never explains limit, its default of 12000, or the meaning of project_id/report_id.

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 frozen report") plus a gating condition ("after source permissions are checked"), and explicitly routes depth-seeking agents to research_explore_report. An agent can distinguish this from the sibling explore tool without opening either schema.

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 an explicit alternative for depth ("use research_explore_report for depth"), which is a real when-to-use rule. It also implies the summary format is the default starting point, but never states when-not to call this tool or what to do if permissions fail.

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