paserver_info

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

With no annotations, the description carries full disclosure. It states the operation is a pure local read with no network touch, enumerates the returned data, and explains that it validates against the registry to produce a clear error on typos, which is a notable behavioral trait. This fully informs the agent of side effects and failure modes.

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 concise and well-structured: it opens with the core purpose, then clarifies scope and output, then gives usage context and error behavior, and finally lists parameters with precise details. Every sentence adds value, and the structure is front-loaded with the most important information.

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 read tool, the description covers all necessary context: purpose, output fields, prerequisites, error handling, and parameter semantics. The presence of an output schema reduces the need to explain return structure in detail, and nothing essential is missing for an agent to call this tool correctly.

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 must compensate. It explains the profile parameter as case-sensitive with an example, and describes studio_root as optional with a default behavior. This adds meaningful context beyond the bare schema definitions, making parameter usage clear.

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 ('Read') and identifies the exact resource ('local info about a PAServer Connection Profile') with an explicit method reference (paclient -l). It clearly differentiates from siblings by stating it is a pure local read that does not touch the network, making its purpose unmistakable.

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?

It provides clear usage context by stating the prerequisite that the profile must already exist in the HKCU registry and explicitly points to list_remote_profiles for enumeration. It also explains error behavior for unknown names. It does not explicitly say when NOT to use it beyond implying local vs. network, but the guidance is sufficient for correct selection.

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