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 and discharges it: it discloses side effects (uses gh login, may create a repo, commits/pushes, triggers a public deploy), merge vs replace behavior, that an existing workflow is never overwritten, that mocks are static, that it refuses to publish into logic repos, and the 128MB constraint. No contradiction with annotations because none exist.

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 long but every block earns its place: purpose and URL pattern up front, then usage rules, side effects, constraints, and next step. The high information density is justified by the tool's complexity and irreversible actions; nothing reads as 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?

For a 7-parameter, no-annotation, no-output-schema tool, this is remarkably complete: it covers user preconditions, permission/ownership, side effects, size limits, when to refuse, and the follow-up call. The only omission is an exact return payload, but the tool tells the agent to use wait_for_github_deploy for the outcome, so nothing needed to call 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 100%, but the description adds decision-level meaning beyond each schema entry: repo must be the user's own and list_github_repos shows candidates; visibility must be asked, has no default, and the URL is public regardless; replace deletes/merges the existing services folder; services_dir supports adding mocks to an existing project. This is substantial added semantics, not schema repetition.

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 a specific verb ('Publish'), resource (mocks to the user's own GitHub repositories), and outcome (shareable URL at api.mockz.io/gh/<owner>/<repo>/). It clearly separates this from the deploy_mock_from_* siblings by positioning them as the 'quick hosted mock' alternative, so an agent can tell them apart without opening schemas.

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?

Explicitly instructs 'ASK THE USER FIRST' with a numbered checklist, tells the agent when to prefer deploy_mock_from_* ('if they are logged in and just want a quick hosted mock'), and when this is the wrong tool ('real logic or state... needs the codegen action and a Go server'). It even chains the next step: '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.