pikvm_endpoints

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

No annotations are provided, so the description carries the burden. It does disclose an important behavioral trait — that this lists paths 'this tool knows' (the wrapper's known set, not necessarily a live probe) — and the output schema covers the return shape. However, it says nothing about side effects, whether results reflect server state, or pagination of the listing.

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 short lines, front-loaded with the purpose and ending with the routing instruction. Nothing is padded, and each line adds a distinct fact (what it returns, how to filter, what to do next).

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 two-optional-param discovery tool with an output schema, this covers purpose, both filters, and the follow-up action. The only omission is any statement about scope or freshness of the catalog, which would matter for an agent deciding whether this reflects the live server.

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 coverage is 0%, so the description must compensate, and it largely does: 'query: a word to look for' explains the search semantics, and it enumerates the accepted group values (system, hid, atx, msd, gpio, streamer, switch, export) that the schema itself does not constrain with an enum. Minor gap: no mention of whether query and group combine or how matching works.

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 PiKVM web API paths this tool knows, with their options.' An agent can tell this is a discovery/catalog tool rather than an execution tool, especially since it names pikvm_call as the executor. It doesn't distinguish itself from the other read-style siblings (pikvm_info, pikvm_type, pikvm_config_read), so it falls short of a 5.

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?

'Use pikvm_call to run one' explicitly hands off to the correct alternative and defines the discovery-then-execute workflow. There are no negative exclusions (e.g. 'not for reading live config — use pikvm_config_read'), which keeps it just under a 5.

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