compare_cpp

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

The description adds behavioral context beyond the annotations: it reveals that source and virtual files are transmitted to a Compiler Explorer backend, notes that diffs are bounded, and clarifies baseline-relative status. These details are useful and do not contradict the read-only, idempotent, non-destructive hints.

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 three sentences, front-loaded with the core function and return values, followed by backend transmission context and a key caveat. Every sentence contributes meaningful information with no redundancy or fluff.

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 tool with a nested schema and an output schema, the description captures the essential semantics: input type, number of configurations, output contents, and a critical non-performance warning. It omits specific details like how baseline is chosen or how window bounds diffs, but the output schema likely covers return structure, making the description reasonably complete.

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 compensate by explaining parameter meanings, but it offers only oblique hints (e.g., 'two to six configurations' implies cases length, 'source and virtual files' maps to source/files). It does not explain the window parameter, baseline selection, or the structure of cases, leaving the agent to rely on schema titles alone.

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 a specific action: compiling a C++ source bundle under 2-6 configurations and returning baseline-relative status, assembly hashes, counts, and bounded unified diffs. This distinguishes compare_cpp from sibling tools like compile_cpp (single configuration) and analyze_cpp (static analysis).

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?

Usage context is implied by the tool's scope (comparing multiple configurations), but the description does not explicitly state when to use this tool versus alternatives such as compile_cpp or analyze_cpp. The only guidance is a caveat that assembly differences are not performance measurements, which serves as a when-not interpretation rather than a use-case directive.

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