gov_attach

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

With no annotations provided, the description carries the full behavioral burden and delivers: it discloses the side effect ('decision resets to pending'), the required follow-up ('run gov_check afterwards'), merge semantics ('repeated calls merge, never drop existing entries'), the trust model ('gov_check trusts the journaled status'), and the return payload. This exceeds what any annotation set typically covers.

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?

Five sentences, zero filler, and the core purpose is front-loaded. Every sentence carries distinct information: what it does, the two usage modes, merge behavior, the trust warning, and the return value. This is dense but optimally organized for an agent scanning top-down.

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 9-parameter tool with two invocation modes and an output schema, the description is complete: it covers the correct parameter combinations, the side effect, the follow-up step, and the key failure mode to avoid. The output schema handles return-value detail, so the description's brief 'Returns the updated gates...' statement is sufficient. No critical information for correct invocation 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 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains that attachments/declarations are name=value strings, and — critically — defines the two valid parameter groupings (gate+status+tool+report_ref vs review+reviewer) that the flattened schema cannot express. The per-parameter definitions remain in the schema, which is appropriate.

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 opens with a specific verb+resource: 'Attach gate evidence, attachments, declarations or a human review to an artifact.' This is a concrete mutation action with clear objects, and it distinguishes the tool from siblings gov_init (creation), gov_check (verification), and gov_report (reporting). An agent can identify what gov_attach does without opening the schema.

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 gives explicit when-to-use conditions: 'Record gate + status + tool + report_ref after a gate tool produced evidence, or review + reviewer after a human reviewed.' It also provides a when-not warning ('Do NOT claim a gate passed when no tool ran') and names gov_check as the required follow-up. However, it never contrasts with gov_init or gov_report, so routing among those siblings is left to inference.

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