verify_translation

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states the action (runs both programs), the output (reports per input: matched, diverged, inconclusive), and handles edge cases (missing runtime or both failing = inconclusive, never a pass). It also explains the grading: a pass is 'cross_checked', a non-pass is 'ungraded'. This is transparent about the tool's behavior and consequences. It does not mention side effects (e.g., whether it modifies state), but for a verification tool, the primary behavior is execution, which is disclosed.

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 structured into three clear paragraphs: purpose, usage/context, and grading semantics. Each sentence adds value—the first paragraph defines the core action, the second gives usage guidance, and the third clarifies the grading. It is slightly longer than minimal but remains efficient, with no fluff. The information is front-loaded with the core purpose, making it easy to scan.

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 (5 parameters, no output schema, no annotations), the description covers the essential aspects: what it does, how it reports results, edge cases (inconclusive), grading semantics, and complementary tool. It does not fully specify the exact return format or what happens when test_inputs is null, but it provides sufficient understanding for an agent to use the tool effectively. The cross-reference to 'grade_basis' is a minor gap but not critical.

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 coverage is 0%, so the description must compensate. It implicitly defines the core parameters: source_code and target_code as 'your source and your port', test_inputs as 'the same inputs' to run both programs, and source_language/target_language through the examples 'python3 -> go, node -> rust' and the mention of 'runtimes'. It explains the behavior of test_inputs (per input reporting) and the importance of languages for runtime selection. While it doesn't explicitly map each parameter in a checklist, it provides enough semantic context for an agent to infer usage.

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 opens with a bold, specific statement: 'PROVE that a port is equivalent: run both programs, compare their output.' It clearly identifies the verb (verify/prove), the resource (a port/translation), and the method (running and comparing). This distinguishes it from siblings like compare_edge_cases (finding edge cases) and compare_execution (comparing execution metrics) by focusing on equivalence validation. The phrasing is unambiguous and not a tautology.

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 explicitly states when to use the tool: 'Use it after porting anything: python3 -> go, node -> rust, a rewritten function against the original.' It also suggests a complementary tool: 'Pair with compare_edge_cases to find the inputs worth testing.' This provides clear use context and hints at an alternative for finding test inputs. It does not explicitly mention when NOT to use it or compare with all alternatives, but the guidance is strong enough for an agent to decide.

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