List ingested documents

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 (historical UNIX documents on the server) and the metadata fields returned, but it does not explicitly mention read-only behavior, pagination, limits, or ordering. The word 'List' implies a non-mutating operation, but more transparency would be beneficial.

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 a single, front-loaded sentence that states the action ('List') and the resource ('historical UNIX documents available on this server'), followed by relevant metadata fields. No redundant or vague language exists.

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 simple no-parameter listing tool, the description adequately covers the resource scope and return metadata. It could mention whether all documents are returned or if pagination is involved, but the simplicity and clarity of the operation make it nearly complete.

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 tool has zero parameters and an empty schema. Since there are no parameters to describe, the baseline of 4 applies. The description adds no parameter-specific information, but nothing is needed in this case.

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 clearly states the tool lists historical UNIX documents with specific metadata fields (title, authors, source URL, page count, description). This verb+resource pair is distinct from sibling tools like search_documents (search vs. list) and list_manpages (manpages vs. documents).

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 implies use when you want an overview of all ingested documents, but it does not explicitly mention alternatives or exclusions. Sibling tools such as search_documents or get_document_info are not referenced, leaving the usage guidance to inference from the tool name and description.

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