jobs_blocked_on_parts

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

With no annotations, the description carries the burden of disclosure. It clearly states the tool returns job cards blocked by short parts, but does not add further behavioral context such as ordering, filtering, or potential performance characteristics. Since it is a read-only report, the core behavior is adequately conveyed, but additional depth is missing.

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 first sentence is excellent and front-loaded. However, the second paragraph is motivational filler ('this is the question... the reason the assistant is worth having') that does not aid tool invocation. It could be removed or condensed, making the description less concise than it could be.

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?

Given the tool has zero parameters, an output schema, and a straightforward purpose, the description is largely complete. It explains what the tool does and the user scenario. The only minor gap is not specifying that it returns a list or any implicit limitations, but the output schema likely covers return details.

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 zero parameters, so the baseline is 4. The description adds no parameter-specific semantics because none exist, but it does clarify the tool's purpose which indirectly helps the agent understand no arguments are needed.

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 first sentence, 'Open job cards that cannot proceed because a required part is short,' uses a specific verb and resource with a clear condition. This distinctly differentiates it from siblings like search_jobs and parts_availability, which have more general or alternative purposes.

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 provides clear context by framing it as the question a service manager asks each morning, implying this tool is for that regular check. It does not explicitly mention alternatives or exclusions, but the situational use case is clear enough to guide the agent.

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