Explain Behavior Assertion

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

With no annotations provided, the description bears the full burden of behavioral disclosure. It does mention that values are 'selected' and that a reason is returned, which adds some context, but it fails to mention return format, error behavior, or whether this is a read-only operation. The description is too sparse to cover the behavioral expectations.

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, efficiently front-loaded with the verb and primary action. There is no fluff or redundant phrasing. However, it is so compact that it sacrifices necessary detail, but the structure itself is clean.

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 4 parameters, no annotations, and no output schema, yet the description covers only the basics. It does not explain what 'traces' are, the role of 'contract', or what constitutes the 'exact reason'. Given the complexity and lack of structured metadata, the description is incomplete.

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 must clarify parameters. It mentions 'baseline/candidate values', giving some meaning to those two, but 'contract' and 'assertion' are left unexplained. The phrase 'return one assertion' could confuse the 'assertion' parameter with the return value. Overall, only partial parameter insight is provided.

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 the tool compares traces and returns one assertion with selected baseline/candidate values and the exact reason. It provides a specific verb ('compare') and resource ('assertion'), and the purpose is distinguishable from siblings like 'render' or 'validate', though it overlaps somewhat with 'behaviorlock_compare' which likely does the comparison without the explanation.

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 gives no explicit guidance on when to use this tool instead of alternatives like behaviorlock_compare or behaviorlock_validate. It implies use when an explanation is needed, but does not state this directly or list any exclusions or conditions.

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