prepare_previs_update

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

Annotations declare readOnlyHint=true, and the description is consistent, reinforcing that nothing is installed. It adds real behavioral context beyond the annotations: the consent protocol, the invalidity of silence/other-version approval, and the rule to only announce success after the plan finishes. What the plan actually contains is not disclosed.

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 core no-install constraint is front-loaded, but the second sentence is a run-on packing consent conditions and the third is a post-call instruction that sits outside the tool's scope. Dense, but structure could be tightened.

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?

There is no output schema, so the description reasonably should say more about the returned plan; it instead focuses on the consent workflow and success announcement, which is the higher-risk part for a read-only preparation step. Adequate but leaves the return value opaque.

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 0%, so the description must carry the parameters, and it does define the two that exist: approved requires human consent for the presented commit, and target_sha is the commit that consent must reference. It does not cover a null target_sha case or the default false behavior.

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 concretely that it returns a plan for the host and explicitly does not install, which separates it from a hypothetical installer. However, it never names the sibling it pairs with (e.g., check_previs_updates or get_previs_update_notes), so differentiation is inferred rather than stated.

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, enforceable rule for setting approved=true: explicit human consent after the question 'Tem atualização, posso instalar?' for the exact target_sha presented, and it rules out silence or approval of another version. It stops short of saying when to call this versus check_previs_updates.

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