fusion_submit_job

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

The description goes well beyond the annotations (which already mark destructiveHint=true). It discloses irreversibility: 'A submitted job CANNOT be recalled.' It also reveals that even a failed attempt has side effects: 'once the request id exists the job is queued.' This adds crucial context about real-world consequences not captured by the structured annotations.

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 dense but not bloated. It front-loads the most critical warning ('THIS STARTS REAL WORK'), then provides scope, return behavior, irreversibility, and parameter guidance. The quoted pod wording adds length but is unique and valuable. A slightly tighter phrasing around the REST create comparison could make it more concise, but every sentence contributes meaning.

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?

This is a high-complexity tool with an output schema available, so return-value explanation is not needed. The description covers the operational essentials: when it applies, how to confirm, what to expect (request id), how parameters must be ordered, and irreversibility. There are no significant gaps for an agent to invoke it correctly.

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 coverage is 0%, so the description carries the full burden. It explains each of the four parameters in the Args section, including examples for `package` and `definition`, and provides detailed positional semantics for `parameters` with the explicit instruction to use empty strings for skipped arguments. It also explains the `confirmed` flag. No parameter is left unexplained.

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?

Description opens with a specific verb and resource: 'Run a Fusion scheduled process (ESS job).' It explicitly distinguishes itself from REST-based operations by saying 'For everything that has no REST resource: Import Payables Invoices, Create Accounting, and the rest of Scheduled Processes.' This clearly separates it from sibling tools like fusion_run_query or fusion_run_report.

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 explicitly states when to use this tool: 'For everything that has no REST resource' and lists concrete example jobs. It also tells the agent to poll with `fusion_job_status` for results. It additionally gives a strong when-not-to-use signal: unlike a REST create, a submitted job cannot be safely failed, so user confirmation is required before setting `confirmed`.

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