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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so "No data is modified. Safe to auto-approve" largely restates them. The description earns credit for disclosing behavior the annotations cannot: EMU unit semantics (914400 per inch, 12700 per point), pagination defaults and the 500 max, and that next_from is null on the last page.

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 safety and prerequisite statements, then a scannable bulleted action list where each line does real work. It is long, but the density is justified for a six-action dispatcher; only the early repeated safety line could be trimmed against the annotations.

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 polymorphic action dispatcher with no output schema, it is largely complete: prerequisites, unit conventions, pagination contract, and per-action payload summaries (shape types sp/pic/cxnSp/tbl, notes, comments, theme, footer). It stops short of describing error or failure behavior when no presentation is open.

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?

The schema is a bare skeleton — action is just a string listing four names and params has no structure at all — so the description carries essentially all parameter meaning. It documents per-action parameters with defaults and ranges (from 0, limit 50/500, include_resolved, format markdown vs json) and clarifies that shape geometry is in EMU unless units is "in" or "pt".

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 names a specific verb family and resource: "Read-only queries on the open presentation (a file whose kind is SLIDE)," and explicitly contrasts with slide_write ("slide_write addresses edits by them"). The six actions are enumerated with one-line scopes, so an agent can distinguish this from slide_write, doc_read, and files_read without opening the 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?

It supplies a prerequisite ("Open the presentation first with files_write(open_file)") and a routing hint ("Start here" on deck_outline), plus a pointer to context() for the full guide. It does not state when to prefer files_read or doc_read over this tool, so the sibling routing is only partially explicit.

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