contribute

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

No annotations exist, so the description carries the behavioral burden. It discloses the key side effect (a GitHub PR is submitted), the preview behavior (shows the diff first), the gh CLI dependency, and optionality. It doesn't explicitly say whether user confirmation is required after the diff or what happens on failure, but the core behavior is not hidden.

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?

Three sentences with the purpose first, workflow details second, and optionality last. Every sentence earns its place, with no filler or redundancy.

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 two-parameter tool with no output schema, the description covers what it does, how it behaves (diff preview), and the environment prerequisite. The only notable omission is the expected result or return flow after the PR is submitted, but that does not block correct 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?

Both parameters are documented in the schema with 100% coverage, and the tool description largely reflects the same meaning. 'description' gains a little context from 'why it helps others,' but no additional format, lookup, or edge-case semantics are provided, so baseline 3 applies.

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 concrete verb and resource: share a skill improvement by submitting a GitHub PR to the upstream repo. This is specific enough to distinguish 'contribute' from siblings like fork_skill or run_skill, even though it doesn't name them.

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 sets clear context that the tool is for sharing improvements back to the community and stresses that it is completely optional, so the agent knows to invoke it only when the user chooses to contribute. It does not explicitly enumerate alternative tools or when not to use it, so it stops short of full routing guidance.

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