Batch Evaluate Translations

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

The description adds valuable behavioral context beyond what annotations provide. While annotations indicate read-only, non-destructive, and idempotent operations, the description reveals this is an evaluation tool that provides scoring and error analysis. It mentions processing 'multiple source-translation pairs' and returning 'aggregate statistics' with individual results, giving insight into the tool's computational nature and output structure that annotations don't cover.

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 well-structured with clear sections (purpose, Args, Returns, Examples) and front-loads the core functionality. However, the Args section duplicates schema information unnecessarily, and the Returns section could be more concise. The Examples section provides good value but adds length. Overall efficient but could be tighter.

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's complexity (6 parameters, batch processing), the description is complete with purpose, parameter explanations, return structure, and usage examples. The comprehensive output schema in the description eliminates the need to explain return values elsewhere. With annotations covering safety aspects and the schema fully documenting parameters, the description provides all necessary contextual information for effective tool use.

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 100% schema description coverage, the description adds minimal value beyond the schema. The Args section essentially repeats schema information about the pairs array structure and optional parameters. The description does provide context about what constitutes a 'translation pair' but doesn't add significant semantic clarification beyond what's already documented in the comprehensive schema descriptions.

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's purpose with specific verbs ('evaluate multiple translation pairs in a batch') and resources ('translation pairs'). It distinguishes from sibling tools by emphasizing batch processing versus individual evaluation (xcomet_evaluate) and error detection (xcomet_detect_errors). The description explicitly mentions 'aggregate statistics' and 'individual results' which further clarifies scope.

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 usage guidance through the 'Examples' section, listing three specific scenarios: evaluating entire documents, comparing MT systems, and identifying problematic segments. This gives clear context for when to use this batch tool versus alternatives like xcomet_evaluate for single pairs. The tool's name and description inherently suggest it's for bulk operations.

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