repository_publish

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

No annotations are provided, so the description carries the burden. It discloses that the tool validates before pushing, pushes explicitly, and avoids force and implicit upstream. However, it does not disclose what happens on validation failure, whether the push is a fast-forward-only push, or what the output schema contains. The description adds some behavioral context but not full transparency.

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?

A single sentence that front-loads the action ('Validate and explicitly push') and immediately states the key constraints ('without force or implicit upstream'). Every word earns its place; there is no filler.

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 tool has 4 parameters, no parameter descriptions, no annotations, and an output schema. The description explains the core behavior but leaves gaps: what does declaration_path do, what does validation check, what is the output shape, and what happens if the remote branch is behind? For a push-like mutation tool, more context would be needed for fully confident invocation.

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. It does not explain any parameter semantics beyond the tool's general behavior. The parameter names (repository_path, remote, remote_branch, declaration_path) are fairly self-explanatory, but the description adds no detail about what declaration_path is used for or how remote_branch is interpreted. Baseline 3 is appropriate because the schema provides names and types but no descriptions.

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 description states a specific verb ('Validate and explicitly push'), a resource ('current HEAD'), and two explicit exclusions ('without force or implicit upstream'). This clearly distinguishes it from sibling tools like repository_commit, repository_pull, and repository_fetch. An agent can tell what this tool does and what it deliberately avoids.

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 implies the tool is for publishing the current branch to a named remote branch, and the exclusions ('without force or implicit upstream') signal when not to use it. It does not explicitly name alternatives like repository_pull or repository_commit, but the context is clear enough for an agent to select it for a push-like operation.

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