Deck outline

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

readOnlyHint and openWorldHint=false already establish this as a safe, local, non-mutating read, so the description's job is mostly to add scoping context. It surfaces useful detail (estimated click steps, file line ranges, notes presence) that an agent would not guess, but says nothing about default-deck resolution, output size on a large deck, or cost.

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?

Two sentences with no filler, but the first is a long field enumeration that buries the operative point ('start here before editing'), which arrives last. Leading with the imperative and trimming the field list would make selection faster.

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 the field catalog is technically redundant, but it does no harm and the pre-edit guidance is genuinely additive. What is missing is the fact that the tool is callable with zero arguments against the server's default deck, which matters for an agent deciding whether prerequisites are needed.

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 only one parameter and schema coverage is 100%, so the schema already documents the dir default fully. The description adds no resolution or path-format guidance beyond what the schema states, matching the baseline for fully-covered schemas.

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 enumerates exactly what the tool produces (every slide in order with index, layout, hidden state, notes flag, line range), so an agent can tell it is a whole-deck structural read distinct from deck_read_slide or deck_frontmatter_schema. It never uses an explicit verb like 'Returns' or 'Lists', leaving the purpose to be inferred from the field catalog.

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?

'Start here before editing an existing deck' gives a concrete workflow trigger, which is more than most read tools offer. It does not name the alternatives it supplants (deck_read_slide for a single slide, deck_check for validation) or say when not to call it, so the routing is only partly closed.

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