commerce_po_approval_workflow

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

Annotations already declare destructive, non-read-only, non-idempotent behavior; the description does not contradict them. It adds useful context that execution routes through the domain-agent dispatcher and takes place under the caller's JWT, tenant, and company scope, which helps the agent understand authorization boundaries.

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 well-structured: an opening one-line action statement, a single routing/scoping sentence, then a short Args block. There is no filler or redundant restatement of schema fields.

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?

An output schema exists, so the missing return-value description is less critical, and the two optional parameters make the surface simple. Still, the definition would be stronger with an example of a valid `message`/`inputs` combination and a brief statement of what the workflow accomplishes or returns.

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%, so the description must explain the parameters, and it does add meaning: `message` is a free-text objective and `inputs` is an optional JSON string of structured inputs. However, it gives no example, allowed shapes, or hints about how the inputs JSON should be structured, leaving ambiguity.

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 uses a clear action verb ('Run') and names a specific resource: the commerce domain agent action `po_approval_workflow`. The 'commerce' qualifier helps distinguish it from sibling tools like `procurement_po_approval_workflow`, though the actual business meaning of the workflow is left mostly to the name.

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 guidance is given for when to choose this tool over alternatives such as `dispatch_domain_agent` or `procurement_po_approval_workflow`. The description explains the mechanical routing, but not the decision context, prerequisites, or situations where this tool is prefered.

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