set_world_gravity

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

Annotations only declare destructive/idempotent/not-read-only; the description goes well beyond by disclosing that it writes two properties, is wrapped in a transaction (undoable), dirties the MAP and therefore requires save_level, and that a read-only .umap causes a silent no-op save. The re-read of GetGravityZ() also warns the agent that the returned gravity_z is measured, not echoed.

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-loaded with what mutates first, then the read-back behavior, then the when-to-use alternative, then the persistence caveats, then the return shape. Dense but every sentence carries load (units, sibling routing, save requirement, return contract); no filler.

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 a two-parameter mutating tool with no output schema, the description supplies the return contract inline (applied_gravity_z, enable_override, gravity_z, success hardcoded), the side effects (dirty map, transaction), the persistence path (save_level), and the alternative tool. Nothing an agent needs to call it correctly is missing.

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 100%, so the baseline is 3, but the description adds real meaning: it clarifies gravity_z lands in GlobalGravityZ and is re-measured via GetGravityZ, ties the Earth reference (~-980) to the default centimetre unit, and explains the override flag's effect on the project default. Only enable_override's optional-default semantics are essentially left to the schema.

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?

Specific verb (set) plus precise resource (exact global gravity on the EDITOR world's WorldSettings) and even names the two properties written (GlobalGravityZ, the Override World Gravity flag). It explicitly differentiates itself from the configure_gravity sibling, so an agent can route between them without opening schemas.

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 decision rule: 'Use this when you want a number; use configure_gravity for named presets (Earth/Moon/Mars/Zero).' It also adds prerequisites (must save_level to persist, check the .umap is not read-only or the save writes nothing), which is exactly the when-to-use/when-it-fails guidance an agent needs.

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