publish_to_github

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

With no annotations, the description carries the full burden of behavioral disclosure and does so strongly. It states side effects up front: uses the user's gh login, may create a repository, commits and pushes, triggers a public deploy, merges an existing services folder unless replace is true, and never overwrites an existing workflow. It also reveals that the public URL means responses are readable by anyone with the link.

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 description is front-loaded with the core action and organized into clear paragraphs for usage, required user decisions, side effects, and constraints. It is long, but the complexity of the tool justifies most of it; a few phrases are slightly redundant with the schema, such as visibility being required with no default.

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 mutating, externally visible action with seven parameters and no output schema, the description is remarkably complete. It covers prerequisites, user confirmation steps, side effects, what the tool refuses to do, spec-size limits, and the follow-up tool to call. It even explains the absence of a returned URL, which is essential when there is no output 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 coverage is 100%, so the schema already handles basic parameter definitions. The description adds worthwhile operational meaning beyond the schema: repo must be user-owned and not invented, candidates can come from list_github_repos, visibility has no default and the resulting URL is public either way, and replace/services_dir merge behavior is clarified.

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 names a specific verb and resource: publishing mocks to the user's own GitHub repository and letting the Mockzilla action deploy them. It also differentiates from sibling tools by labeling this the free path for unauthenticated users, a code-review-friendly option, and by explicitly noting that this tool returns no URL while wait_for_github_deploy does.

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?

It provides explicit when-to-use and when-not-to-use guidance: prefer deploy_mock_from_* for quick logged-in hosted mocks, use this for repo-based/free hosting, and avoid it for real logic or state, which needs the codegen path. It also chains the workflow by instructing the agent to ask the user first, consult list_github_repos, possibly run simplify, and then call wait_for_github_deploy.

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