run_transform_map

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

The description adds substantial behavioral context beyond the annotations: it explains that the tool creates a sys_import_set_run record, that whether this starts the transform is not verified, and what environment flags are required. These caveats are critical for a non-idempotent, open-world mutation and are exactly what an agent needs before invoking it.

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?

The description is front-loaded with the action and the record creation, followed by the key caveats. It is dense but every clause carries useful information, though the parenthetical prerequisite list makes it slightly harder to scan.

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?

Given a mutating tool with no output schema, the description covers the important operational caveats and prerequisites. It could say more about what is returned or what failure looks like, but the essential behavioral uncertainty is disclosed.

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 input schema already documents both required parameters. The description reinforces the domain context but does not add parameter-level details beyond what the schema provides.

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 description states a specific verb and resource: request a Transform Map run on an Import Set by creating a sys_import_set_run record. It is clear what the tool does, but it does not explicitly differentiate itself from nearby tools such as list_transform_maps, get_transform_map, list_import_sets, or get_import_set.

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 by the required transform_map_sys_id and import_set_sys_id parameters, and the description gives important prerequisite conditions (WRITE_ENABLED=true, SCRIPTING_ENABLED=true in some cases). However, it does not explicitly say when to use this tool versus alternatives or when not to use it.

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