pve_call_endpoint

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does a strong job: explains validation of operationId and path params, the read-only write gate, the two env-var mechanisms for enabling writes, and the confirm requirement for destructive operations. This is rich behavioral context for a generic dispatching tool. It could mention what the response looks like or error behavior, but the write-gate and destructive confirm disclosure are substantial.

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 compact paragraph of ~60 words covering purpose, gating rules, and usage guidance. It's dense but not bloated; every clause earns its place. It could be structured slightly better with separators, but it front-loads the core purpose and adds crucial behavioral details efficiently.

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 generic API-dispatch tool with 1 required parameter, nested object params, and no output schema, the description is substantially complete. It covers the validating behavior, write-gating across two env surfaces, destructive confirm flow, and directs to the describe tool for param specifics. The main gap is that it doesn't describe the shape of the JSON response or error-handling behavior, but for a low-param generic dispatcher paired with a describe tool, this is a strong, complete description.

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% in the structured fields provided, but the actual input schema itself has descriptive text for each parameter (operation_id, path_params, confirm, params). The description adds directional value by telling the agent to use describe_endpoint for exact params. For this tool the schema already annotates parameters reasonably; the description complements rather than repeats. Given nested object params for path_params and body fields, the pointer to describe_endpoint is genuinely helpful and raises this above baseline.

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 what the tool does: 'Call a Proxmox VE API endpoint and return its JSON response.' It names the specific verb+resource (call a PVE API endpoint), mentions validation against a catalog, the read/write gate, then execution. It distinguishes from siblings by noting pve_ prefix (as opposed to pdm_) and referencing pve_describe_endpoint for param details, though it doesn't explicitly differentiate from pdm_call_endpoint.

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?

Excellent usage guidance. It explicitly states when reads run vs writes and how to enable writes (PROXMOX_ALLOW_WRITES=true vs PVE_ALLOW_WRITES=true). It explicitly directs the user to 'Use pve_describe_endpoint first to learn the exact params,' giving clear instruction on sequencing with a sibling tool. The confirm gate for destructive operations is also disclosed in the schema.

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