List recent captures

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds value by disclosing the returned field set and warning that results land under the legacy 'yoinks' key. It stops short of noting ordering guarantees or what an empty index yields, which keeps it at 4 rather than 5.

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 sentences: purpose and returned fields first, sibling routing second, the legacy-key caveat last. Every clause carries information and nothing is repeated from the schema.

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 no output schema, the description correctly compensates by enumerating the returned fields and naming the response key. For a single optional-parameter list tool with full annotation coverage, nothing an agent needs in order to call it is missing.

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 100% and the 'limit' property is already documented as a response-size cap that does not alter stored data. The description's 'up to the requested number of items' merely restates that, adding no format or interaction detail, so the baseline 3 applies.

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 a specific verb and resource ('List the newest saved captures from the local index') plus the fields returned, so the agent knows exactly what it gets without opening a schema. It also names the two nearest siblings it is not, making it distinguishable from search_uoinks and search_library.

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?

Explicit routing: 'Use to browse recent additions without a query; use search_uoinks for matching text or search_library for bounded citation-ready retrieval.' The when-to-use and when-to-use-something-else conditions are both spelled out with named alternatives.

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