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

Annotations indicate this is a non-read-only, non-idempotent action, and the description's word 'Record' aligns with a mutating operation. The description adds useful behavioral context by explaining how to attribute the verdict to agent vs. human and how to link the vote back to the originating comparison. It does not fully disclose whether duplicate votes overwrite or append, but the annotations already cover the main safety profile.

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 compact, front-loaded with the main action, and then gives targeted parameter guidance in short, readable sentences. Every sentence contributes useful information; there is no fluff or restatement of the tool name.

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 simple recording tool with one required parameter and no output schema, the description provides sufficient context to invoke it correctly. It explains the relationship to compare_search, the required winner values, the judged_by provenance rule, and the need to preserve query/track_b linkage. The omitted 'reason' parameter is optional given its default and therefore does not block correct usage.

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?

With 0% schema description coverage, the description must carry the semantic load, and it largely does: it defines the allowed values for 'winner' ('A', 'B', or 'tie') and 'judged_by' ('agent' vs 'human'), and explains the role of 'query' and 'track_b'. The only gap is the 'reason' parameter, which is completely undocumented in both the schema and the description.

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 ('Record an A/B verdict') and ties it explicitly to a sibling tool ('after compare_search'). It also defines the core domain terms 'winner', 'tie', and 'judged_by', making the tool's purpose unmistakable. This clearly differentiates it from similar comparison or logging tools.

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 tells the agent when to use the tool ('after compare_search') and gives explicit instructions for provenance ('judged_by: agent for your own judgment, human when relaying the human's answer'). It also instructs the caller to pass the same query and track_b as the comparison, which is a strong usage constraint. It does not explicitly list when not to use it, but the context is clear enough.

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