pve_list_endpoints

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

No annotations are provided, so the description carries the full burden. The description reveals it's a read-only listing tool (read/write/destructive fields are listed output, not side effects), which is non-destructive by nature. However, it doesn't mention pagination behavior, output size limits beyond the limit param, or whether results are truncated. The description is adequate but lacks depth on behavior edge cases.

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?

Two sentences, front-loaded with purpose and returned fields. The second sentence is valuable workflow guidance. Minor waste: the filter list partially duplicates the schema parameter names, but the field enumeration adds useful output context. Efficient overall.

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 list/discovery tool with no output schema, the description enumerates what will be returned (operationId, method, path, category, description, read/write, destructive), which is valuable. It explains the workflow pipeline and filter options. Lacks explicit statement about it being read-only/safe, but the nature of listing makes that reasonably inferable. The default limit of 200 and filtering guidance partially compensates for the large surface area.

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% per context signals, yet all 7 parameters actually have descriptive schema text (filter behavior, defaults). The description adds the limit default (200) and advises narrowing with filters for big surfaces, plus guides users to call with no args to see all categories. This is a 0-param structure (params wraps an object), so the nested param object's individual descriptions carry meaning. The description adds marginal strategic guidance.on top of what schemas already say.

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 it lists Proxmox VE API endpoints and enumerates the returned fields (operationId, method, path, category, description, read/write, destructive). It distinguishes itself from siblings by referenceing pve_describe_endpoint and pve_call_endpoint as the next steps, positioning this as the discovery tool in a pipeline.

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?

States explicit filters (category, resource, method, reads/writes, search) and gives clear when-to-use guidance: 'Use this to discover an endpoint, then pve_describe_endpoint for its parameters and pve_call_endpoint to execute it.' This positions the tool within its sibling workflow and differentiates it from pve_describe_endpoint and pve_call_endpoint.

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