outline

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

With no annotations, the description still discloses real behavioral traits: deeper content is collapsed into counts, and refresh forces a re-read because caching is normally automatic. It omits any statement of read-only safety, permissions, or response size limits, but it goes well beyond restating the schema.

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-loads the return content, then annotates each parameter compactly in a second block. No filler sentences, though the '(mm)' units and 'live bounding boxes' phrasing are terse to the point of jargon.

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 described, and three of four parameters are explained. The undocumented max_lines parameter is exactly the kind of truncation control an agent needs to know about, leaving the definition short of complete for a 4-parameter tool.

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?

Schema description coverage is 0%, so the description carries the full burden — and it documents root (default: whole page), depth (levels to expand), and refresh semantics with useful context. max_lines is left completely unexplained, which is the one real 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 opening sentence names the resource precisely — the object tree with ids, labels, text snippets and bounding boxes — so an agent knows it retrieves a document outline. However, it uses a noun phrase rather than a verb and never distinguishes itself from close siblings like structure, inspect, or find.

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?

The description explains what each parameter does but gives no guidance on when to reach for outline versus the many adjacent tools (structure, inspect, find, selection). Nothing states preconditions or the situations this tool is meant for.

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