list_items

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

With no annotations, the description carries the full burden: it discloses the scope (whole document, not one page) and the exact per-item shape returned, which tells an agent this is a lightweight read-only inventory rather than content retrieval. It omits any note on size limits, pagination, or behavior on documents with no items.

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?

Three short sentences, front-loaded with the resource, then the row shape, then the usage hint. Minor waste in the opening noun-fragment, but every sentence contributes.

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 two-parameter read-only list tool with an output schema, this covers what it returns, its scope and when to reach for it. The remaining gap is guidance on next steps (fetching text or image once the page is known) and any volume caveats.

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 coverage is 100%, so both the document reference and the kind filter (table/figure/caption, empty = all) are already fully documented in the schema. The description adds only the document-wide scope framing and no further meaning for kind or document.

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 the specific resource (tables, figures, captions of the whole document) and what each row contains (element ID, page, region, caption). It's clearly a document-wide inventory, which distinguishes it from page-scoped siblings like get_page_map or get_element_text, though it doesn't name them explicitly.

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?

"Use it to find a table or a figure when you do not know its page" gives a concrete triggering scenario and implicitly excludes page-known lookups. It stops short of naming the alternative tools (e.g. get_element_text, search_text) for the cases it excludes.

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