mistral_request

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description productively elaborates on them: the destructive behavior is auto-accepted file edits via the default --agent accept-edits, with a defined boundary ('dangerous ops such as shell stay gated'). It also discloses the runtime deferral behavior. This adds genuine context beyond the annotations without contradicting them.

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?

Two sentences of roughly 50 words pack the core action, the sync/defer behavior, the input requirement, and the safety-relevant default. Each clause earns its place and the most important fact (synchronous execution) is front-loaded.

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 29-parameter tool with no output schema, the schema itself is exceptionally rich, and the description captures the non-obvious runtime contract: when it returns vs. defers, the required input shape, and the default agent with safety gating. The only gap is the absence of any hint about the response shape, which matters more because no output schema exists to fill that void.

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 100%, so parameter meaning is already fully documented. The tool description adds only the aggregate constraint 'exactly one of prompt or promptParts' (already mirrored in each parameter's mutual-exclusivity note) and the default agent accept-edits, which permissionMode's schema description does not state. This is marginal additive value over an already-complete schema.

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?

States a specific verb+resource ('Run a Mistral Vibe CLI request synchronously') and immediately differentiates from the async sibling through the auto-defer behavior ('when async jobs are enabled, auto-defers to a pollable job past the sync deadline'). The 'Requires exactly one of prompt or promptParts' constraint and the default-agent note add operative specificity well beyond a restatement of the tool 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?

The description conveys when the call returns versus defers to a pollable job, which implies the sync-use case, and states the hard input requirement (exactly one of prompt or promptParts). However, it never names the alternative (mistral_request_async) or states explicit when-to-use/when-not-to-use conditions. Usage context is present but implied rather than stated as exclusions.

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