sumo_qa_reviewing_before_merge

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

With no annotations, the description carries the full behavioral burden. It does disclose one genuine guardrail — it "refuses to claim safe-to-merge without fresh verification evidence" — which tells the agent the output is gated. But it omits whether the tool only reads or also mutates, what verification artifacts it requires, and what it returns, leaving significant gaps for a zero-annotation tool.

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?

Two compact sentences with the routing precondition front-loaded and no filler. The second sentence is somewhat compressed — the negation phrasing demands a re-read — but nothing is wasted.

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 zero-parameter workflow step with no output schema, the agent gets when-to-use and one guardrail but not what the review actually examines, what evidence counts as "fresh", or what the result looks like. Adequate to invoke, incomplete to anticipate.

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?

The tool takes no parameters, so schema coverage is moot and the baseline for zero-param tools applies. There is nothing for the description to disambiguate at the argument level.

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 trigger phrases ("review my changes", "is this safe to merge", "what could break") plus the name make the resource and intent identifiable as a pre-merge change review. However, the description never states the action explicitly (e.g. "reviews the diff and assesses merge risk"); the agent must infer it from quoted user utterances. It does distinguish itself from siblings by being the routed destination of sumo_qa_deciding_approach.

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?

It states an explicit precondition ("Use after sumo-qa-deciding-approach routes here") and gives concrete user-intent triggers that select this tool over the ~45 siblings. Nothing about when to reach for it 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.