configure_workload

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description builds on this by adding non-obvious behavioral details: it 'preserves existing workloads and experiments,' 'never executes the command,' and 'returns the next discovery step.' These disclose side-effect scope and non-execution, going beyond the structured hints. No contradiction exists.

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 compact and front-loaded with the primary purpose. It repeats the 'without executing' idea twice ('without executing it' and 'It never executes the command'), which is slightly redundant but not wasteful. Overall, it earns its sentences in a short, readable format.

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?

The description explains the tool's immediate behavior and one update scenario, but lacks broader workflow context. It does not explain how configure_workload fits with sibling tools like run_experiment or plan_experiment, what 'validated' entails, or how to use the create operation effectively. Given the tool's complexity and the rich sibling set, this is a notable 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 only 17%, so the description must compensate. Yet it only explains one usage pattern involving operation and a 'current configuration_id' (which likely refers to expected_configuration_id, but uses an imprecise name). The other 11 parameters—name, argv, cwd, oracle, identity, requirements, etc.—receive no added explanation, leaving a significant gap for such a complex input 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?

The description opens with a clear verb-resource pair: 'Write one validated named workload without executing it.' It immediately distinguishes this configuration tool from execution-oriented siblings by stating 'It never executes the command,' and further clarifies its scope with 'Writes only the project workload configuration.' This is specific and unambiguous.

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?

The description provides a concrete usage pattern: 'Use operation='replace' with the current configuration_id to update an existing workload.' This gives clear context for the update case. However, it does not explicitly name alternatives (e.g., run_experiment for execution) or state when not to use the tool, so it falls short of a 5.

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