config_upload_update

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

Annotations declare destructiveHint=true, and the description backs that up with the specific destructive side effect most agents would miss: omitting new_name silently renames the snippet from the file stem. It also discloses the persistence model (database write, scheduler applies later) and an explicit limitation (cannot confirm it is live), which no annotation conveys.

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?

Three short clauses, front-loaded with the action and the base64 requirement, followed by the alternative and then the persistence caveat. Telegraphic but every clause carries a distinct, load-bearing fact.

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 an eight-parameter destructive mutation with no output schema, the description covers the surprising side effect, the alternative tool, and the deferred-application model, which is what an agent most needs. It stops short of stating that the prior content is lost or whether type/service must match the existing snippet, leaving a small gap.

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 description coverage is 100%, so all eight parameters, including the new_name rename behavior and the service/global default, are already documented in the schema. The description echoes the new_name trap for emphasis but adds no syntax or constraint beyond the structured fields, so the baseline 3 applies.

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?

"Replace one snippet's content from a base64 file" gives a specific verb (replace), a scoped resource (one snippet's content), and the input medium (base64 file). The singular "one snippet" implicitly separates it from the bulk sibling configs_upload, and the next clause explicitly separates it from config_update.

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?

"Use config_update for text" names the primary alternative and the condition that selects it, which is exactly the routing decision an agent faces. It does not address when to prefer configs_upload (bulk) or config_create instead, so the alternative map is clear but not complete.

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