repo_script

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

With no annotations, the description carries the full burden and discharges much of it: it discloses ssh delivery, root execution from a temp dir, cleanup afterward, that the checked-out version is pinned and shown with commit/uncommitted-changes/hash, that secrets are read from mia's environment and never displayed, and that installTo keeps the prior copy as .bak-<time>. It omits explicit permission/auth requirements and error-handling traits, so it is not exhaustive.

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?

Information-dense and front-loaded: the core action appears first, followed by delivery/execution behavior, then provenance and the secrets model. It is fairly long, but nearly every clause carries new information, so it earns most of its length.

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 15-parameter, no-annotation, no-output-schema tool this is a fairly complete description: it explains the execution model, the safe plan/apply flow, provenance, and the secrets and install variants. Remaining gaps (behavior of timeoutSec, batch, continueOnError, skipUnreachable) are covered by schema descriptions, so an agent has enough to call it 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 coverage is high (87%), setting a baseline of 3, but the description adds meaning beyond the schema for the workflow-critical params: envFrom (secrets sourced from mia's own environment, never shown), with (companion files kept at same relative paths), apply/planHash (dry-run then apply, refused if state changed), and installTo (cron re-runs the installed copy). It adds genuine semantics rather than restating the 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?

States a specific verb+resource: it runs the user's own fleet scripts from a local repo checkout on hosts, and names the exact kinds of scripts (deploy/migrate-blacklist.sh etc.). This clearly distinguishes it from generic remote-execution siblings like host_exec, since it emphasizes 'exactly the checked-out version runs' with commit/hash provenance.

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 lays out the intended two-phase workflow (dry run with apply=false and a planHash, then apply=true) and explains the envFrom/secrets path, which is real usage guidance. It does not explicitly contrast with alternatives such as host_exec or service_action, so it stops short of a full when/when-not routing statement.

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