pdm_describe_endpoint

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It does describe what the tool returns (full endpoint spec, request sample) which adds value, but it doesn't disclose side effects (none expected for a describe operation), latency, or failure modes. There's no contradiction with annotations, and the description adds useful context about the return value, but doesn't go deeper into behavioral characteristics.

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, information-dense sentence that lists all return components compactly then gives the usage directive. No wasted words, but it's somewhat long and could benefit from slight structural front-loading of the purpose. Still, it earns its length given the tool's role in preparing for PDMS calls.

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?

Given the tool's moderate complexity (single parameter, no output schema but returns rich endpoint spec data), the description adequately explains the return contents and usage. It doesn't fully compensate for the absence of an output schema, but the enumeration of returned components (types, formats, enums, constraints, permissions, sample) gives a strong picture. Sibling tools exist for listing endpoints and calling them, which is referenced. A return format description isn't strictly needed here since the description tells you what's in the spec.

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%, so the description carries the full burden for explaining the single parameter. The description mentions operationId usage and its format ('get_nodes' or 'post_nodes_node_qemu'), and references 'list_endpoints' as the source for valid values. It also explains what the operationId represents. With only one parameter and the description covering its semantics well, this is solid.

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 uses a specific verb+resource structure: 'Get the full spec for one Proxmox Datacenter Manager endpoint' with detailed enumeration of what the spec includes (method, path, path params, query/body params with types/formats/enums, response schema, permissions, request sample). It clearly distinguishes from siblings by naming pdm_call_endpoint as the after-step and referencing pdm_list_endpoints behavior.

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 explicitly states when to use it: 'Call before pdm_call_endpoint so you send exactly the right params.' This provides clear usage context and pairs it with the follow-up action. It doesn't explicitly state when-not-to-use, but the 'call before pdm_call_endpoint' instruction effectively guides correct sequencing among the sibling tools.

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