update_global_source_contents

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

The only annotation is readOnlyHint=false, so the description carries most of the burden and does well: it discloses upsert semantics (create-or-overwrite), an ordering requirement (read before write), and a hard human-approval gate. It does not state permission requirements or exactly what happens to entries omitted from the array, which keeps it from a 5.

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?

Front-loads the purpose, then the entry shape, then the mandatory-safety block in caps. Every sentence earns its place and the ordering matches how an agent consumes it. The 'IMPORTANT' block is slightly long but justified by the destructive-potential of an unconfirmed upsert.

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?

With no output schema and a single, fully documented array parameter, the description supplies the missing behavioral context (upsert, read-first, confirmation). Return-value behavior is unspecified but not needed here; only the approval/rollback consequence of the write is left implicit.

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 the nested fields are already documented; the description only restates three of the four entry keys and omits type_component. Baseline 3 applies since the schema does the heavy lifting and the description adds no format or validation detail beyond it.

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 a specific verb+resource (Update multilingual contents) and adds the key semantic qualifier '(upsert)', which tells the agent it may both create and overwrite. It also enumerates the entry shape (global_source_id, language_code, content), making it clearly distinguishable from siblings like update_global_source_element or update_global_source.

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 an explicit prerequisite workflow: read with get_global_source_contents first, show the user the diff, and obtain explicit confirmation before writing. It names the sibling tool to use for the read step. It does not, however, disambiguate against update_global_source_element or update_global_source, so the routing is only partially complete.

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