List collection data

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

Even though annotations declare readOnlyHint=true, the description goes well beyond that baseline by detailing pagination mechanics (limit, total, next_cursor), the full filter operator set, and a notable caveat: 'items moved mid-page can be skipped or repeated.' This discloses non-obvious behavioral edge cases that an agent would otherwise be unaware of.

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?

The description is dense but every sentence contributes something essential: purpose, UI exclusion, paging format, filter semantics, and a paging caveat. It is front-loaded with the core function, then logically flows to details. There is no fluff or repetition.

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?

With an output schema present, the description needn't enumerate return fields in detail, but it still mentions the key return elements (id, total, next_cursor). It covers pagination, filtering, and potential anomalies, making it fully sufficient for an agent to use effectively, especially given readOnlyHint and openWorldHint annotations.

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 already documents each parameter, but the description adds substantial semantic depth. It explains how 'match' works (bare value equals vs. operator object), how comparisons behave for numeric/string/ISO dates, and what 'next_cursor' signifies. This goes far beyond the schema's simple descriptions, making the parameter behavior actionable.

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 opens with a specific verb and resource: 'Read items in full — every field, plus the item id you need to update or delete it.' This clearly states the tool's function and distinguishes it from sibling write tools (data_add_item, data_update_item) by highlighting that it returns IDs needed for those operations. It also contrasts with open_app by explicitly noting 'No UI (use open_app for that).'

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 provides clear context for when to use this tool: to read full items and obtain IDs for updates/deletes, or to page through data with filtering. It explicitly names an alternative (open_app) for UI needs, and the phrase 'use open_app for that' gives a direct when-not-to-use signal. While it doesn't enumerate all sibling data_* tools, the read vs. write distinction is obvious from the first sentence.

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