audio_artifact_validate

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It mentions it 'validates' and 'reports gaps,' but does not clarify whether this is a read-only operation, whether it modifies the artifact, if it requires specific access, or what the side effects might be. No mention of error conditions or whether it validates against a schema. The behavior beyond the action is largely unspecified.

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 a single sentence with no filler or repetition. It is front-loaded with the main action and outcome. However, its extreme brevity borders on under-specification, though for pure conciseness and structure it is effective. The sentence earns its place with essential content.

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 a nested object parameter, no output schema, and no annotations, the description is severely inadequate. It does not explain what 'versioned' means, how to specify the artifact, what 'reproducibility gaps' are, or what the validation result looks like. An agent would be unable to correctly invoke this tool beyond guessing the parameter content. The description leaves critical context unaddressed.

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 schema has 0% description coverage for the sole parameter 'artifact,' and the tool description provides no additional meaning. It does not explain what constitutes an 'artifact,' its structure, required fields, or how the versioned nature is reflected in the parameter. The description entirely fails to compensate for the empty schema documentation.

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 states a specific action ('Validate') on a specific resource ('versioned calibration artifact') and mentions a concrete outcome ('report reproducibility gaps'). This makes the tool's primary function clear. It partially differentiates from siblings like audio_artifact_create and audio_artifact_migrate, but does not explicitly name alternatives; a clear but not fully distinguished purpose.

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?

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, context, or situations where another sibling tool would be more appropriate. For example, it does not say 'use this after artifact creation' or 'use audio_session_replay_validate for session-level validation.' There is no exclusions or routing information.

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