ssh_puppet_noop

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

With no annotations, the description does real work by disclosing that the run is non-mutating and verbose, which is the key behavioral fact. It says nothing about prerequisites (Puppet installed, root privileges, credentials set up via ssh_setup_credentials) or that Puppet returns a nonzero exit code when drift is detected despite applying nothing.

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?

One compact, front-loaded sentence that earns its place and wastes nothing. Slightly under-specified for the gaps it needs to close rather than over-long.

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?

An output schema exists, so return values need no explanation, and the single parameter is self-naming. What remains missing is surrounding context — root/credential prerequisites and the fact that a nonzero exit may mean drift rather than failure — which keeps it below complete.

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?

One required parameter, hostname, with 0% schema description coverage. The name is self-explanatory and the description adds no syntax (FQDN vs alias vs IP) or format guidance, so this sits at the baseline for a trivial single-param schema.

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?

Specific verb (run Puppet agent), resource (Puppet), and mode (no-op/dry run with verbose output). No sibling does anything Puppet-related, and the parenthetical '(dry run)' removes any ambiguity about what 'no-op' means.

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?

Usage is implied by the name and the dry-run framing — an agent can infer this is the safe preview before applying a real Puppet run. But no use cases, no exclusions, and no pointer to alternatives (e.g. use ssh_execute_sudo for a real apply) are given.

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