Creates an Approval Order Request (AOR) in Oracle HCM Cloud. Use it to initiate approval workflows; without write mode, the request remains pending approval, preventing unintended changes.
Create AOR (approval unless --write).
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes |
Changes observed during successful MCP inspections.
v0.4.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false, the annotation already tells the agent this is a mutation; the description adds little beyond a cryptic approval/write caveat. It does not disclose side effects, approval semantics, required permissions, or what happens to the created AOR.
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 extremely short, but brevity here is under-specification rather than useful conciseness. It contains no structured guidance and front-loads an unresolved, ambiguous parenthetical.
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?
For a write operation with an opaque body and no output schema, this description is far from complete. It omits the meaning of AOR, the approval workflow, the body structure, and any indication of the result or next steps.
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 single required 'body' parameter has 0% schema description coverage and is a free-form object with no properties documented. The description gives no hint about required fields, structure, or expected content, so the agent cannot construct a valid body.
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 names the action and resource ('Create AOR'), but the acronym AOR is never expanded and the parenthetical '(approval unless --write)' muddies whether the tool creates an approval, an AOR, or a direct write. It does not differentiate this create tool from the many sibling create tools.
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 when-to-use or when-not-to-use context is given relative to hcm_get_aor, hcm_update_aor, hcm_delete_aor, or hcm_approve_write. The only conditional cue, 'unless --write', refers to a flag that does not appear in the input schema, so it cannot guide invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.