Write Hermes skill patch proposal

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

The description explicitly discloses the tool's safety profile: 'proposal-only', 'performs no skill writes or git operations'. Notably, annotations already include destructiveHint=false and the name contains 'proposal', but the description adds value by explicitly stating it creates artifacts (proposal) and does NOT write to skills or git — meaningful behavioral context beyond the annotations. However, it doesn't disclose what the output/return value looks like, and the output schema exists but the description doesn't reference it.

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 a single concise sentence that front-loads the key information: 'proposal-only' and 'no skill writes or git operations'. Every phrase earns its place and there is zero wasted text. It could arguably add a sentence on the replacement semantics (old_string/new_string matching), but as-is it's a compact, well-structured description.

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?

Given 9 parameters, an output schema, and a moderately complex read-modify-propose workflow, the description is somewhat thin. It doesn't explain the source resolution hierarchy (home/source/profile/toolkit_root), the matching semantics of old_string (first vs replace_all), or what happens if the old_string isn't found. The output schema exists but the description doesn't describe the proposal artifact format. The safety framing is good, but for a proposal-generating tool with this parameter surface, more operational guidance is warranted.

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%, meaning the description adds no parameter documentation. With 9 parameters, including a required old_string/new_string pair and optional home/source/profile/toolkit_root for locating the skill, the description does not explain how these relate to the readback or what source resolution means. The 'bounded skill-file readback' mention hints at a workflow but doesn't clarify parameter semantics. Baseline 3 is appropriate since the schema itself is reasonably self-explanatory for the required fields.

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 clearly states 'Write proposal-only skill patch artifacts after bounded skill-file readback; performs no skill writes or git operations.' This uses a specific verb+resource ('write skill patch proposal') and explicitly distinguishes itself from the sibling tool hermes_skill_patch_apply by noting it is 'proposal-only'. It lacks some depth (doesn't mention that readback is a prerequisite step the agent must complete), but the core purpose is clear and differentiates from siblings.

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 implies usage through the 'proposal-only' framing and the prerequisite 'bounded skill-file readback'. However, it doesn't explicitly state when to choose this vs. hermes_skill_patch_apply, or what distinguishes a proposal from an application scenario. The 'performs no skill writes or git operations' clause implicitly tells the agent this is the safe/preview variant, but excluding the apply sibling by name leaves guidance implicit rather than explicit.

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