hydra_check_job

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. It adds useful behavioral context by revealing twelve deterministic rules and giving examples of what is checked (missing operations, cast issues, plaintext secrets). It doesn't over-explain outputs, which the output schema covers.

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 longer than strictly necessary, but each sentence earns its place: definition, sibling contrast, rule examples, and call timing. It is front-loaded with the core purpose and remains readable. Minor over-specificity in the rule list keeps it from a 5.

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 read-only checker with two string parameters and an output schema, the description covers the main things an agent needs: what the tool does, how it differs from the validation sibling, and when to call it. It doesn't describe the exact response shape, but the output schema can carry that. The missing parameter format guidance is the main completeness gap.

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 0%, so the description needed to compensate for both parameters. It only implies that user_request is what the user asked for and job_path refers to the written job; it never states expected formats or how they should be supplied. This is a clear gap, since no parameter descriptions exist in the 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 and resource: 'Check that a job does what the user actually asked for.' It explicitly contrasts with hydra_validate_job, making the tool's role distinct from a sibling. The reference to twelve deterministic rules further sharpens what 'check' means.

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?

Gives explicit sequencing: 'Call this AFTER writing a job, before presenting it.' It also names the alternative hydra_validate_job and explains the division of labor (YAML correctness vs. answering the request), so an agent can decide between the two. No misleading conditions.

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