Draft a governance-compliant GitHub issue (HITL)

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

Annotations say non-read-only, non-destructive, idempotent, closed-world; the description goes further by naming the failure mode (GOVERNANCE_VIOLATION on new runtime dependency, embedded key/password, missing reproduction, duplicateSearchPerformed:false), the policy set checked, the HITL contract file, and the fact that no network or GitHub write path exists in the server. The 'file' output mode writing into the sandbox is consistent with readOnlyHint=false rather than contradicting 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?

Front-loaded with the core contract (draft locally, never submit) and packed with useful specifics, with no filler sentences. It is dense and long-claused, and the targetRepo routing sentence restates what the enum descriptions already say, which costs a little.

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 an 11-parameter tool with nested reproduction and an output schema, the description covers scope, policy validation, error signaling, output modes and the HITL handoff. The one gap is what the accompanying compliance report actually contains, though the output schema likely covers that.

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%, so the baseline is 3; the description earns more by linking parameters to behavior — duplicateSearchPerformed:false is a hard violation, outputMode:'file' writes a .md inside the sandbox, and targetRepo selects between engine, CLI and wrapper semantics. Most of this duplicates the schema text, but the enforcement consequences are genuinely additional.

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?

States a specific verb and resource ('Produce a LOCAL GitHub issue draft + compliance report') and immediately bounds the scope with 'NEVER submit it'. A reader knows exactly what artifact comes back and that no external write occurs, which no sibling tool in this PKI-oriented set does.

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 clear precondition ('Use it only after reproducing a defect with TEST material') and a clear post-condition ('Present the draft AND the report to the user, then STOP'), plus the targetRepo routing rule for choosing among repos. No alternative tool is named, but none of the sibling tools overlaps this function, so the guidance is essentially complete.

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