atualizar_base

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

With no annotations, the description carries the full burden and does well: it discloses the side effect (writes to the local database), that data comes from the official site, and rough performance costs (SINAPI ~1 minute, ORSE a few minutes). It omits whether existing data is overwritten or what happens on failure, keeping it out of the top band.

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?

Purpose is front-loaded in one sentence, followed by tight per-parameter lines with no filler. Every statement carries information the caller needs, and the size is well matched to a three-parameter tool.

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?

An output schema exists, so return values need not be explained, and the description covers parameters, side effect, and timing well for a mutation tool with no annotations. The remaining gap is failure/overwrite behavior, which keeps it short of fully complete.

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 compensate, and it does thoroughly: it enumerates the valid base values (SINAPI, SICRO, ORSE, SEINFRA) that the schema lacks as an enum, states the conditional ufs requirement per base and the 27-UF default, and gives competencia's format plus the SEINFRA version exception and empty-means-latest 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?

The opening sentence gives a concrete verb and resource: downloads a base from the official site and writes it into the local database. The role is distinguishable from siblings like buscar_precos or orcar, though the description never explicitly names an alternative tool, so it falls just short of full sibling differentiation.

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?

Usage is implied rather than stated: it is clearly the download/update operation, and the per-parameter rules (SICRO requires ufs, SINAPI filters them) are given. However, there is no explicit when-to-use vs when-not guidance, e.g. checking bases_disponiveis first or preferring this over querying the current local base.

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