set_github_output

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write, and "Append" is consistent with that, adding the useful detail that existing file content is preserved rather than overwritten. It does not disclose what happens when neither GITHUB_OUTPUT nor output_path is available, whether the name is validated, or whether the call fails silently — meaningful gaps for a write tool, but the annotation baseline is met.

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, front-loaded with the action and target, with the file-source detail in a compact parenthetical. Nothing is redundant or padded.

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 simple three-parameter append operation with an output schema (so return values need not be described), the description covers the essential mechanics. The only notable omission is fallback/error behavior when no output file is resolvable, which keeps it from a 5.

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 carry parameter meaning, and it does: name and value are explained via the NAME=VALUE line format, and output_path is explained as the explicit alternative to the GITHUB_OUTPUT environment variable. Remaining gaps are minor (no constraints on valid name characters, no note that output_path's null default means fall back to the env var).

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 pairs a specific verb ("Append") with a specific resource (a GitHub Actions output file) and even states the line format NAME=VALUE, so an agent knows exactly what the tool does. It does not name or contrast any sibling, but none of the listed siblings perform a comparable operation, so confusion risk is low.

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?

Usage is implied rather than stated: mentioning GITHUB_OUTPUT or output_path tells the agent this is for writing step outputs inside a GitHub Actions run, and the parenthetical hints at the two target modes. There is no explicit when-to-use/when-not guidance, no mention of prerequisites (e.g., running inside an Actions environment), and no alternative such as writing environment variables.

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