git_push_execute

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

The description richly discloses behavior beyond the annotations: the broker holds the credential, no token enters the sandbox, force is conditional on the envelope grant, refusals are cited in FRANK with errno and queued as human-required, and success returns the pushed sha and citation id. This far exceeds the sparse readOnlyHint=false/destructiveHint=false annotations.

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 main action is front-loaded and the brokered-push context is efficiently stated. The ruling date, quoted operator message, and docs pointer add relevant security context but make the description longer than strictly necessary; overall it remains well organized.

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?

The description covers the action, authorization model, force constraints, refusal behavior, and return value, which is especially important given there is no output schema. The main omission is detailed semantics for the optional parameters, but their defaults and non-required status keep the gap minor.

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?

With 0% schema description coverage, the description carries the burden of explaining parameters, and it does add meaning for branch, checkout, remote, repo, force, and app_id. However, `project`, `task_id`, and `envelope_id` remain unexplained, leaving a noticeable gap even though they are optional with defaults.

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 names the exact operation: push `branch` at `checkout` to `remote` under the git.push envelope. It also distinguishes itself from the sibling `envelope_apply` by noting this is not a new capability but an envelope application with the act attached.

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 gives clear usage context: this is the brokered push path where the agent initiates, the broker holds the credential, and no token enters a sandbox. It also clarifies force is honored only when the envelope grants it and that refusals route to the human-required queue, though it does not explicitly list alternative tools or exclusion conditions.

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