Create a JobBOSS2 report

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

Annotations already signal a non-read-only, open-world, non-idempotent operation. The description adds valuable transparency by stating that ECI's OpenAPI document does not define the request body fields or response schema, which is critical for an agent deciding whether it can trust schema validation or needs other knowledge. It does not, however, disclose whether report generation is asynchronous or what side effects occur beyond submitting the request.

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 two sentences with no filler. The action is stated first, followed by a necessary caveat about the missing schema definitions. Every sentence earns its place.

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?

The schema caveat is important, but for a submit operation with an unconstrained object parameter, the agent still lacks guidance on what fields to include, what this request means for report generation, or how to follow up (e.g., using jobboss2_get_report). The output schema and annotations help, but the description alone is not fully sufficient for confident invocation.

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 input schema has a single generic `data` object with 0% description coverage. The description only notes that fields are undefined by ECI's OpenAPI document, which explains why the schema is vague but gives the agent no concrete meaning, examples, or guidance for constructing the `data` payload.

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 specific verb and resource: 'Submit a JobBOSS2 report request.' It clearly identifies this as a report-submission action rather than a retrieval or generic list operation. However, it does not explicitly distinguish itself from siblings like jobboss2_create_report vs jobboss2_get_report or jobboss2_create, leaving some ambiguity about whether it triggers generation or just records a request.

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 gives no when-to-use guidance and no contrast with alternatives such as jobboss2_get_report for retrieving results or jobboss2_create for general creation. The use case is only implied by the title and name, not explained in the description.

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