push_config_start

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

With no annotations, the description carries the full burden and does: it discloses the candidate-config lock, the commit_check -> commit confirmed -> health check -> confirm -> unlock sequence, that the committed change equals the returned diff, the RPC timeout used (180 s SRX branch / 120 s otherwise), and that an unconfirmed commit rolls back after `confirm_timeout` if the server dies. It also enumerates rejection cases (push already in progress, too many retained jobs, config switch during a job) and the `status: rejected` error shape.

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?

Front-loaded correctly: what it does, then when to choose it over the sibling, then behavior, then return shape, then args. It is long but nearly every line carries operational information; only the diff/result return values are restated twice (once narratively, once in the return JSON).

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?

No output schema exists, so the description supplies the full return shape (`job_id`, `status`, `hostname`, `diff`, `result`, `poll_with`, `poll_after_seconds`) plus the possible terminal statuses and the rejected error object. For an async, mutating, locking tool with zero annotation coverage, nothing an agent needs in order to call and poll it correctly is missing.

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%, but the Args block documents all eight parameters, including the mutual exclusion between `config_file` and `set_commands`, the dry_run default, confirm_timeout in minutes, and the config_path empty-string fallback. It loses a point because several entries defer to `push_config` ('see push_config') rather than being self-contained, and no type/range detail is added.

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 first sentence states a specific verb and resource ('Start push_config as a background job') and names exactly what it returns (diff and job_id) without waiting for the commit. It explicitly contrasts itself with the `push_config` sibling, so an agent can pick between the two without opening either 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 concrete selection criteria against the alternative: use this when the client cuts a tool call at ~60 s (hosted connectors), when the device commits slowly (SRX300/320/340/345), or when `push_config` answered 'Still running'. It also prescribes the follow-up pattern — poll `push_config_result(job_id)` every ~10 s until status is not running.

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