Skip to main content
Glama

same_energy_prepare_update

Read-only

Prepares a host update command for terminal execution after explicit approval and target-commit validation; returns no runnable command without user consent.

Instructions

Prepara um comando de atualização para executar no host; não instala por si só.

approved=true SOMENTE se o usuário concordou explicitamente depois da pergunta 'Tem atualização, posso instalar?'. target_sha deve ser o commit apresentado nessa pergunta. Sem concordância ou com outro commit, retorna a pergunta e nenhum comando executável. Execute o plano no terminal do agente e só anuncie sucesso após a instalação terminar.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "same_energy_prepare_update"
  }
}

Input Schema

NameRequiredDescriptionDefault
approvedNo
target_shaNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description is consistent with that — the tool only prepares, it does not install. It adds genuine context beyond the annotations: what happens when approval is missing (a question is returned, no command), plus downstream instructions to run the plan and only report success after installation finishes. It stops short of describing the returned payload structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, followed by the approval gate, the fallback behavior, and the execution instruction. Every sentence is functional, though the final sentence about running the plan in the terminal drifts from describing the tool into describing the agent's workflow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, read-only tool with no output schema, the definition covers the gating logic, the negative path, and the follow-through. The only real omission is what a successful return actually contains (command text, plan artifact, target commit echoed back), which the agent could use to act on the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, and it does: 'approved=true SOMENTE se o usuário concordou explicitamente' defines the boolean's exact activation condition, and 'target_sha deve ser o commit apresentado nessa pergunta' pins the string to a specific provenance. Both parameters gain meaning that the bare schema cannot supply.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Prepara um comando de atualização') and immediately bounds the scope with 'não instala por si só', so the agent can distinguish it from an actual install step. It does not name a sibling such as same_energy_check_updates, so the differentiation is conceptual rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition for each branch: approved=true only after the user answered 'Tem atualização, posso instalar?', target_sha must be the commit from that same question, and any other case returns the question with no executable command. This is a clear when/when-not rule set with no inference required.

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