run_test_suite

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

With no annotations provided, the description must disclose behavior on its own. It only states 'validate or execute', but doesn't mention side effects (e.g., whether execution is destructive, whether it generates reports, whether it requires a running session) or any constraints. This is insufficient for an agent to predict the tool's impact, especially given the tool's complexity.

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 a single, concise sentence that front-loads the tool's purpose. It avoids unnecessary detail and stays focused, scoring high on efficiency. There is no redundant wording or 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?

Despite having eight parameters, nested options, and an output schema, the one-sentence description does not explain overall workflow, mode selection, or parameter combinations (e.g., session_id vs suite_file_path). The schema covers individual parameters, but the description lacks the high-level context needed for a tool this complex, especially with sibling tools that may overlap in functionality.

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?

The schema already provides descriptions for all parameters (100% coverage), so the description does not need to repeat them. The description adds nothing about parameter usage, but the baseline is 3 given complete schema coverage. The description's lack of parameter context doesn't degrade the score, as the schema fills the gap.

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 clearly states the tool's function: 'Validate or execute a Robot Framework suite.' It specifies the resource (Robot Framework suite) and the actions (validate/execute), which is enough to distinguish it from sibling tools that target individual steps or flows. The verb is specific and the scope is 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 offers no guidance on when to use this tool over alternatives like build_test_suite, execute_flow, or execute_step. It neither states conditions nor recommends alternatives, leaving the agent to infer usage from the tool name and schema. There is no mention of prerequisites or typical scenarios.

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