workflow.machine.control

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

No annotations are provided, so the description must carry the full behavioral disclosure burden. It fails to do so: it does not state whether the tool is read-only or destructive, what side effects occur (e.g., does modifying the machine trigger changes in the analysis? Are there irreversible actions?), or what the response looks like. The only hint is the action parameter, but without enum values or documentation, the behavior is opaque.

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 tool is under-specified, not concise. While the description is short, it is insufficient for the tool's complexity (8 parameters, 0% schema coverage). A useful description would need more detail to be effective.

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 the high complexity (8 parameters, 2 required) and no output schema or annotations, the description is completely inadequate. It provides none of the necessary context for an AI agent to understand what actions can be performed, what parameters are valid for each action, or what the tool's side effects are.

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 0%, and the description adds no parameter details. The schema shows 8 parameters (including action, enable, activity, advanced, activities, session_id, incremental, workflow_name) with no type constraints or enums. The description provides zero insight into what these parameters mean, how they relate, or valid combinations (e.g., which actions require which parameters).

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 'Control workflow machine runtime' is too vague. It uses a generic verb 'Control' and an abstract noun 'machine runtime', failing to specify what actions are possible or what resource is being manipulated. It does not distinguish from the many sibling workflow tools like workflow.machine.status, workflow.start, workflow.stop, etc., which likely share similar context.

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?

No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives like workflow.machine.status or workflow.describe. There are no prerequisites, context requirements, or mentions of 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.