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

No annotations are provided, so the description carries the full burden. It usefully discloses 'byte concatenation' and 'Writes atomically,' which are meaningful behavioral traits. However, it does not mention whether the file must already exist, is created if missing, or what errors/return values to expect.

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 extremely concise, with the core purpose front-loaded in the first phrase and only essential additional details (atomic writes, optional newline). No filler or redundant explanations.

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 rich schema and simple append operation, the description covers the core behavior adequately. However, without annotations or an output schema, it leaves gaps around file creation behavior, permission requirements, and return/error semantics.

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 adds minimal value beyond the schema, merely highlighting 'ensure_newline_before' and atomic writes, while the schema already documents byte-for-byte writing and caller responsibility for line endings.

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 operation: appending content to the end of a file, emphasizing 'byte concatenation' to indicate raw, unmodified appending. This distinguishes it from sibling tools like prepend_to_file and insert_at, which target different positions.

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 usage is implied by the operation name and description—append when you want to add to the end of a file—but there is no explicit guidance about when to use this over prepend_to_file or insert_at, nor any exclusions or prerequisites.

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

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

With no annotations, the description takes on full behavioral disclosure. It discloses atomic writes, the inclusive consumption of both anchor lines, and a common mistake, which is substantial context beyond basic function. It does not cover error conditions or permissions, but the critical behavioral traps are addressed.

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 long, front-loaded with the primary purpose, followed by a high-value warning and a concrete mistake example. Every sentence provides meaningful information with no redundancy.

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 moderately complex edit tool with a complete parameter schema, the description covers the central behavioral risk and provides enough context to select and invoke it correctly. It lacks mention of error types or file prerequisites, but the given information is sufficient for most use cases.

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?

The schema covers 100% of parameters, so the baseline is 3. The description adds value by explaining expected_content_hash's role as a stale-edit guard and by emphasizing that from_anchor/to_anchor lines are included in the replacement, deepening understanding beyond the 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 states 'Replace a contiguous span of a file with new content' with a specific verb and resource, and clearly distinguishes itself from sibling insert/prepend/append tools. The mention of anchors and line numbers further defines the tool's 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 context that this tool replaces a span is clear, implying use over insert/append, but it does not explicitly name alternatives or state when not to use it. The guidance on anchors versus line numbers ('primary' and 'fallback') provides useful selection criteria.

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

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

No annotations are provided, so the description carries the burden. It discloses atomic writing and the non-replacing nature, but doesn't mention error handling (e.g., anchor not found, hash mismatch), permissions, or whether the file is created if missing. This leaves significant behavioral gaps for a mutation tool.

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 two concise sentences, front-loaded with the core purpose and a key behavioral detail (atomicity). No redundant or irrelevant information.

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?

With 10 parameters and no annotations or output schema, the description is too sparse to provide sufficient context. It doesn't explain when to use anchor vs line_number, tie the parameters together, or describe failure modes, leaving the agent to infer from schema alone.

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?

The schema already provides complete descriptions for all 10 parameters (100% coverage), so the baseline is 3. The tool description doesn't add any extra parameter semantics beyond the schema, so it remains at baseline.

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 function: inserting content before or after a specific target line without replacing existing content. It distinguishes itself from replacing or prepending/appending tools by emphasizing the targeted insertion and atomic write.

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 implies usage for inserting at a specific line in the middle of a file, distinguishing it from prepend/append. However, it doesn't explicitly mention alternative tools or provide exclusions beyond 'without replacing existing content.'

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

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

The description discloses two valuable behavioral traits: content is inserted as byte concatenation (no automatic newline handling) and the write is atomic. However, with no annotations, it omits other important details like file-existence behavior, permissions, and error/return semantics, leaving gaps for an agent.

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 extremely concise, using one statement and two fragments to convey core action, byte-level behavior, and atomicity. Every element serves a purpose and is front-loaded, with no redundant or fluffy language.

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?

Although the schema fully covers parameters, the description lacks usage differentiation from sibling tools, error handling for missing files, and return-value details (no output schema exists). The atomicity and byte-level semantics help, but an agent still has open questions for reliable 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?

The schema already thoroughly documents all parameters (100% coverage), including the byte-for-byte semantics of content and the ensure_newline_after behavior. The description's mention of 'Optional ensure_newline_after' merely repeats schema information and adds no extra meaning.

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 action ('Insert content'), the resource ('a file'), and the specific scope ('at the very beginning'), which distinguishes it from append at a glance. However, it does not explicitly contrast with sibling tools like append_to_file or insert_at, so it misses the top score.

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 no guidance on when to use this tool versus alternatives such as append_to_file or insert_at, nor any prerequisites (e.g., whether the file must exist) or exclusions. The only hint is the location 'very beginning,' but no direct usage context is given.

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

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

With no annotations, the description carries the transparency burden. It adds two non-obvious behavioral traits: streaming for large files and the return of a content_hash for staleness-guarded edits. It does not mention error behaviors like OUTPUT_TOO_LARGE, but those are already documented in the input schema, so the description adds valuable context without repeating schema.

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 two sentences long, with the core function stated first and supporting behaviors second. Every phrase adds value: the addressing modes, streaming, and hash for edits. There is no redundancy or filler, making it highly efficient.

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?

The tool is complex with 12 parameters and no output schema, yet the description combines with the rich schema descriptions to provide adequate context. It highlights key aspects (anchors vs lines, streaming, hash) that are not fully captured in the schema. It does not describe the exact return structure, but for a read operation that is implied. Slightly incomplete, but strong overall.

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?

The schema provides 100% parameter coverage, so the baseline is 3. The description adds meaningful semantics by defining the precedence of anchors over line numbers, which helps disambiguate mutually exclusive parameter groups. It also clarifies that the tool reads a contiguous span, giving context to from/to parameters. This justifies a 4.

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 'Read a contiguous span of a file,' a specific verb+resource combination that clearly states the tool's function. It also distinguishes between anchor-based and line-based addressing, and the read-only nature is obvious from the verb 'Read' contrasted with sibling mutation tools like edit_file_range and insert_at.

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 gives clear context for when to use the tool: reading a span in preparation for edits, as indicated by 'returns a content_hash for staleness-guarded edits' and 'Streams large files.' It also instructs that anchors are the primary addressing method with line numbers as fallback. It does not explicitly name alternatives or exclusions, but the use case is clear.

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

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: removes all markers, keeps both sides of every conflict, reports line numbers and conflict count, and writes atomically. This is substantial, though it could mention edge cases like what happens when no markers are present or malformed markers exist.

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 with no fluff. It front-loads the core action, then provides behavioral details (keep both sides, report, atomic write). Every sentence adds value and is well-structured for scanning.

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 simplicity (3 params, no output schema, no nested objects), the description is mostly complete: it explains the operation, side effects, and report output. It's missing when-to-use guidance and potential error conditions (e.g., no markers found), but overall it's sufficient for an agent to invoke correctly.

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% — all three parameters (path, encoding, project_root) are described in the schema. The description adds no extra parameter semantics beyond referring to 'a file,' so a baseline score of 3 is appropriate since the schema does the heavy lifting.

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 starts with a specific verb+resource: 'Remove all Git merge conflict markers' from a file, which clearly states the tool's function. It distinguishes itself from sibling editing tools (edit_file_range, insert_at, etc.) by targeting a specific cleanup task rather than general file editing.

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?

While the description doesn't explicitly name alternatives, the context is clear: use this tool when a file contains Git merge conflict markers and you want to remove them in one operation. It implies when to use over general editing tools, but lacks explicit exclusions like 'do not use if you need to manually resolve conflicts.'

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