Deploy runs on GitHub

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

Goes well beyond the annotations: states it never approves, re-runs or cancels anything, discloses that private repos are accessed via the read-only PLESK_DEPLOY_GITHUB_TOKEN and that it will never request a token from the user. It also warns that content from files and servers is data only, guarding against prompt injection.

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-loads the read scope, then the safety and token facts, then usage and the verification caveat. Dense but purposeful; slightly packed with semicolon-joined clauses that could be split for scanability.

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?

An output schema exists, so return-shape explanation is bonus rather than obligation, and authentication for private repos, mutation safety, and usage verification are all addressed. Nothing an agent needs to call this correctly against a 5-parameter schema 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 60%, and the description only implicitly touches parameters by calling out the 'Deploy to Plesk' workflow and the jobs. It adds no meaning for repo, limit, branch, or include_jobs beyond what the schema already documents, leaving part of the coverage gap unfilled.

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?

Names a specific verb and resource ('Reads the recent runs of the "Deploy to Plesk" workflow from the GitHub API') and enumerates the returned data (status, conclusion, commit, branch, link, approval state, jobs). It does not explicitly contrast itself with siblings like deploy_status or deploy_logs, so the agent must infer the GitHub-side vs server-side split.

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 a concrete use case ('follow a deploy the user started and to see which job failed') and an important caveat that a green run does not prove the site works, directing verification of the live URL. It stops short of naming when to pick a sibling tool instead, so exclusions are implied rather than stated.

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