job_status

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

The annotations declare readOnlyHint=true and destructiveHint=false, which establishes this as a safe read. Beyond that, the description adds no behavioral context: it does not list possible job states (queued/running/succeeded/failed), say whether the result is retained or expires, or describe what happens with an unknown or expired job_id. For a status-polling tool this is a meaningful gap.

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 single sentence is front-loaded and free of filler, so nothing is wasteful. However, at eight words it is under-specified rather than genuinely concise, and the space saved is not spent on any detail that would help an agent invoke the tool correctly.

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?

With no output schema, the description must describe what a caller should expect to receive, and it only gestures at 'progress and result' without shape. For a polling endpoint whose whole value is the returned state, the definition leaves the agent unable to know how to interpret a response or when to stop polling.

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?

There are two parameters with only 50% schema description coverage. The bot parameter is documented in the schema, but job_id is undocumented in both schema and description, and the definition never clarifies its format or where the caller obtains it. The description compensates for none of that gap.

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 identifies the resource (a background job) and what is returned (progress and result), but it uses no verb and never frames the action as polling or fetching status. It gives no contrast with siblings, though most listed siblings are Discord admin operations rather than job tools, so the ambiguity is moderate rather than severe.

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?

There is no indication of when to call this: no mention of polling after starting a background job, no guidance on how often to call, no statement about what to do while the job is still running, and no alternatives referenced. The agent must infer the entire workflow from the name.

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