norns_deploy

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

With no annotations, the description carries the full burden and mostly succeeds: it discloses the dry-run-first plan, the no-delete guarantee ('Never deletes on the norns'), the backup target ~/norns-mcp-backups/, and post-push sha256 verification per file. The significant flaw is that it conditions live mode on a '--live' flag that does not exist among the three declared parameters, leaving the agent unsure how live mode is actually triggered.

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?

Roughly four dense clauses, front-loaded with the 'WRITE.' mode marker and then ordered by risk: default behavior, safety constraint, then the live path. Every sentence adds a fact; nothing repeats the schema or the title.

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 destructive-capable write tool with no annotations and an output schema (which covers the returned plan), the description supplies enough to call it safely: dry-run default, backup location, idempotency-ish no-delete guarantee, verification step. The outstanding gap is the phantom '--live' flag, which leaves the activation mechanism for live mode unresolved against the actual schema.

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 and only partly does: it explains that confirm=true is required for live pushes and that <name> forms the remote folder path, but never explains local_dir's expected shape (trailing slash, relative vs absolute) or how name defaults to null (presumably derived from the folder basename). Worse, it references a '--live' parameter that is absent from the schema, which actively misleads parameter construction.

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 ('Push a script folder from this Mac to ~/dust/code/<name>/ with rsync over SSH') plus the transport. The leading 'WRITE.' token immediately separates it from read-only siblings like norns_read_script and norns_list_scripts, so an agent can route to it without opening the schema.

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?

Gives conditional guidance for the risky path: 'Live (needs --live and confirm=true)' tells the agent exactly what activating a real push requires, and implies the default is a safe dry run. It does not name sibling alternatives (e.g. using norns_read_script first to inspect contents) or state when a deploy is inappropriate, so it stops short of full when/when-not coverage.

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