list_deviances_by_checker

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

No annotations are provided, so the description must disclose behavioral traits. It only states it 'gets' deviances, which implies a read operation, but it does not confirm safety (no destruction, no side effects), nor does it explain pagination behavior or the purpose of the required 'expression' field in the body. This lack of transparency could lead to misuse.

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 extremely concise: two sentences. The first sentence states the purpose, and the second provides a critical usage note. There is no wasted text, and the key information 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?

The tool has 7 parameters, including a nested required body with an 'expression' field, and no output schema. The description does not explain the expression parameter, nor does it describe the return format or pagination details. While the schema covers parameter descriptions, the overall description lacks completeness for understanding how to use the tool effectively, especially for the complex body parameter.

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 input schema has 100% description coverage for all parameters. The description adds value by clarifying that profileId selects a configuration profile (lens vs container) and suggests how to obtain it if missing. Other parameters like page, perPage, etc., are adequately described in the schema, so the description provides marginal extra value beyond the baseline of 3.

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 clearly states 'Get all deviances by checker', which is a specific verb and resource. It also clarifies that profileId selects a configuration profile (a lens, not a container), adding precision. While the tool name is self-descriptive, the description reinforces its purpose and distinguishes it from sibling tools like list_deviances_by_directory.

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 explicit guidance on how to handle the profileId parameter: if the user hasn't specified a profile, call get_preferred_profile or get_preferences and use preferredProfileId, and not to assume profile 1. This is helpful. However, it does not explicitly clarify when to use this tool versus siblings like list_deviances_by_directory_and_checker, which would be needed for a perfect score.

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