atlas_smart_merge

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

With no annotations provided, the description carries the transparency burden. It discloses that it's AI-powered, can detect semantic conflicts, preserve both sides, generate tests, and provide confidence scoring. However, it does not explicitly state whether it modifies files, whether autoResolve causes irreversible changes, or require a clean working tree. The marketing tagline ('Never waste hours') adds no operational transparency. Could be more explicit about safety/state changes.

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 as a feature list with a clear title and bullet points. It is reasonably concise and front-loaded. However, the final marketing sentence ('Never waste hours...') is unnecessary and dilutes usefulness. The core bullet list is informative without being bloated, earning a 4.

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 complex tool with 6 parameters and no output schema or annotations, the description covers key features but misses operational details: return values, error conditions, prerequisite git state, and whether auto-resolutions are applied to the working tree. It explains what the tool does but not fully how results are returned or what side effects occur. The schema covers parameters, but the description is not fully complete for safe invocation.

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 100%, so the baseline is 3. The description mentions features like 'Generate test cases' and 'Confidence scoring', which loosely map to generateTests and confidenceThreshold, but it doesn't add parameter-level semantics beyond the schema. The schema already documents each parameter clearly, so the description adds little extra value.

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: 'Automatically resolve merge conflicts using AI.' It uses a specific verb ('resolve') and resource ('merge conflicts'), and distinguishes itself from sibling tools like atlas_git by focusing on AI-powered conflict resolution, semantic understanding, and test generation. The title also reinforces this.

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 indicates the tool is for merge conflicts and mentions 'Integration with git workflow,' giving clear context for when to use it. It doesn't explicitly state when not to use it or name alternatives, but the focused scope ('merge conflicts') and features like 'autoResolve' and 'interactive suggestions' imply appropriate usage. Lacks explicit exclusions but is fairly clear.

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