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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the creation act and says nothing about side effects such as whether the buffer becomes active, what happens if the name already exists, or whether content is inserted.

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 a single, direct sentence with no wasted words. However, its extreme brevity means it sacrifices useful context, though what is present is clear and front-loaded.

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 three parameters, no annotations, no output schema, and many sibling tools, a one-sentence description is insufficient. It lacks information about required vs optional parameters, behavior on name conflicts, whether the buffer is auto-switched to, and how mode/content are used.

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 name, mode, and content are already documented in the schema. The description adds no additional param semantics, but the baseline of 3 applies because the schema carries the detailed parameter 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 uses a specific verb and resource ('Create a new buffer'), clearly indicating the operation. It is essentially a restatement of the tool name but is not vague and is distinguishable from sibling buffer read/write/edit/kill operations.

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?

No guidance is given about when to use this tool versus alternatives like emacs_buffer_write, emacs_buffer_edit, or emacs_buffer_switch. The description does not mention prerequisites or situations where one sibling would be preferred.

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 of behavioral disclosure. It only says 'targeted edits' and 'find and replace', omitting important behavior such as whether all occurrences are replaced or only the first, what happens if old_text is not found, whether the buffer must already exist, and the implications of the save parameter. The schema explains 'save' but not the edit behavior.

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 a single sentence with no fluff: 'Apply targeted edits to a buffer (find and replace)'. It is front-loaded with the action and resource, and every word earns its place.

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 mutation tool with no annotations and no output schema, the description is minimal. It omits behavior around unmatched text, multiple matches, buffer existence, and save defaults. An agent can infer the basic call from the schema, but unsupported edge cases are left unspecified, which is a notable gap.

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 each parameter already has a description. The tool description adds no new parameter meaning beyond echoing 'find and replace', which maps to old_text and new_text. The baseline of 3 is appropriate because 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 states a specific verb and resource: 'Apply targeted edits to a buffer' with 'find and replace' clarifying the mechanism. It is clear and distinguishes itself from sibling tools like emacs_buffer_write, which would replace the entire buffer, though it does not explicitly name that alternative.

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?

No guidance is provided on when to use this tool versus alternatives such as emacs_buffer_write or emacs_eval. The description states what it does but does not specify conditions, exclusions, or named alternatives, leaving the selection decision entirely to the agent.

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 must carry behavioral and safety information. It only says 'Close/kill a buffer', leaving the consequences for unsaved changes, confirmation behavior, and irreversibility implicit, and the force parameter is described only in the schema, not in the tool description.

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 short and front-loaded, with no filler words. It is lean rather than poorly structured, though it is thin enough that behavioral details are left to the schema.

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?

This is minimally viable for a simple two-parameter tool whose parameters are fully documented in the schema. However, because there are no annotations and no output schema, the description does not convey result behavior, failure modes, or destructive consequences on its own.

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 100% because both 'buffer' and 'force' have descriptions in the input schema. The tool description adds no parameter-level meaning beyond that, so the baseline score of 3 is appropriate.

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?

'Close/kill a buffer' names a specific action and target resource, and 'kill' is a distinct operation among the sibling buffer tools. It could more explicitly differentiate itself from buffer_switch or buffer_edit, but there is little real ambiguity about what the tool does.

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, nor does it mention that buffers with unsaved changes will not be killed unless force is used. Usage context is only implied by the tool name and the wording 'Close/kill a buffer'.

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 must carry the disclosure burden. It conveys a read-only listing operation, but it does not specify what metadata is returned, whether the default excludes hidden buffers, or any side effects. Basic transparency is present, but detail is lacking.

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 a single focused sentence that starts with the core action and adds only the essential resource and metadata qualifier. There is no filler or repetition.

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 simple one-parameter list tool, the description plus schema is mostly sufficient. However, it does not clarify the default hidden-buffer behavior or describe the return shape, which would help an agent use it correctly without extra assumptions.

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 only parameter, include_hidden, is fully documented in the schema with a clear description. The tool description adds no parameter-level detail, but none is needed because schema coverage is 100%.

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 identifies the operation: list buffers with metadata, using specific verb-resource language. It is distinct from siblings like emacs_buffer_read or emacs_buffer_switch, though it does not explicitly differentiate itself.

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 intended use case—enumerating open buffers—is implied by the verb and resource, but there is no explicit guidance about when to choose this tool over siblings or when to set include_hidden. It is adequate but relies on inference.

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 of behavioral disclosure, but it only states that content is read. Nothing is said about the non-mutating guarantee, behavior on a nonexistent buffer, whether the active buffer changes, or return format—all material for an agent invoking this 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 a single front-loaded sentence with zero filler, stating the verb and resource immediately. It is appropriately sized for a one-parameter tool, though the brevity is partly why behavioral and usage dimensions score lower.

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 simple 1-parameter tool without an output schema, the purpose and the parameter are adequately covered. However, the total absence of behavioral context (error behavior, read-only guarantee) and any sibling differentiation leaves noticeable gaps, especially given the large tool family. Adequate but not 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?

Schema description coverage is 100%; the schema already documents the single 'buffer' parameter with a concrete example ('main.ts' or '*scratch*'). The tool description adds no parameter-level meaning beyond this, so the baseline 3 applies.

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 uses a specific verb ('read') with a clear resource ('contents of an Emacs buffer'), which naturally separates it from write/edit/kill siblings. However, it does not explicitly differentiate from close relatives like emacs_buffer_list or emacs_org_read, and 'contents' is slightly ambiguous about whether it returns raw text.

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?

No guidance is given about when to use this tool versus emacs_buffer_list, emacs_buffer_switch, emacs_file_open, or emacs_org_read. Usage is only weakly implied by the verb 'read'; no exclusions, conditions, or alternatives are mentioned.

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 states the core side effect (the chosen buffer becomes current) but does not mention what happens if the buffer does not exist, whether the buffer must already be created, or whether an error is returned.

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?

One short, front-loaded sentence states the action and the result with no filler.

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?

Adequate for a one-parameter state-change tool, but with no annotations or output schema it leaves unknown failure behavior (e.g., missing buffer) and does not clarify whether an exact buffer name is required. This is a gap an agent would have to learn by trial.

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 description does not need to re-explain the buffer parameter. It adds no meaning beyond the schema, which is acceptable given the baseline for full coverage.

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?

Uses a specific verb ('switch to') and resource ('buffer') and clarifies the intended effect ('make it current'), so it is immediately distinguishable from sibling operations like emacs_buffer_read, emacs_buffer_list, or emacs_buffer_kill.

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?

Provides no guidance on when to choose this instead of related buffer tools such as emacs_buffer_read, emacs_buffer_edit, or emacs_buffer_create, nor any exclusions or prerequisites. The only context is the name and a terse definition.

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 must disclose behavioral traits; 'replace' hints at destructive overwrite, but it does not state what happens to unsaved changes, whether the buffer must already exist, or whether content is saved by default. These are material gaps for a mutating 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 a single, short sentence that is easy to scan and front-loads the action. It is efficient, though 'write/replace' is slightly redundant.

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 mutating tool with no annotations and no output schema, the description is too sparse. It omits when to choose this tool over siblings and important behavioral caveats, making it only minimally viable for a simple buffer operation.

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 parameters are already documented. The description adds the meaning of 'content' as new full-buffer content, but provides no additional semantics beyond the schema.

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 uses a specific verb ('write/replace') and identifies the resource (Emacs buffer content). It clearly conveys full-content replacement, which helps distinguish it from emacs_buffer_edit, though it does not explicitly name that sibling.

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?

No guidance is provided about when to use this tool over emacs_buffer_create, emacs_buffer_edit, or emacs_file_save. The phrase 'write/replace' implies whole-buffer replacement, but no explicit conditions or exclusions are 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 full burden of disclosing behavior, but it only says 'Get a summary'. It does not state whether the tool is read-only, what the return format is, whether it opens a buffer, or whether it has any side effects. The verb 'Get' implies a read operation, but little else 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 a single concise sentence with no filler. The essential information is front-loaded and every word contributes to meaning.

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 description is adequate for a simple comparison tool with fully documented parameters, but it leaves gaps around output format and usage context. With no output schema and no annotations, an agent would benefit from knowing what the summary looks like and when to prefer this over emacs_ediff_* tools.

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?

Input schema coverage is 100%, so all three parameters already have meaning in the schema. The description adds no further parameter details, but that is acceptable given the high schema coverage; a baseline of 3 is appropriate.

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 a specific verb ('Get a summary') and resource ('differences between two files or buffers'), making the core function clear. It does not explicitly differentiate from sibling tools like emacs_ediff_files or emacs_git_diff, but the word 'summary' implies a non-interactive, non-git-specific comparison.

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?

No guidance is provided about when to use this tool versus the sibling ediff or git diff tools. The description does not mention whether this is appropriate for quick summaries while ediff is for interactive comparison, or any other 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?

With no annotations provided, the description carries the full behavioral burden. It only says 'three-way comparison of files', which implies a read-only diff operation, but does not disclose whether it launches an interactive Ediff session, modifies files, returns a diff, or has any side effects. This is a significant gap for a tool with no annotation support.

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 a single, concise sentence that communicates the core function and primary use case with no wasted words. It is front-loaded with the essential purpose and immediately conveys the differentiating 'three-way' aspect.

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 there is no output schema, no annotations, and four parameters, the description is too thin to be complete. It does not explain what the agent should expect as a result (e.g., unified diff text, interactive buffers, exit codes), nor does it provide enough nuance to safely invoke the tool in a merge-conflict scenario where file roles matter.

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 100%, so the input schema already documents all three required file parameters and the optional format parameter. The description adds no parameter-level detail beyond the schema, but the baseline of 3 applies because the schema does the heavy lifting. The merge-conflict phrasing hints at the roles of 'mine', 'theirs', and 'ancestor' but does not explicitly map to parameters.

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 (three-way comparison) on a specific resource (files) and adds the merge-conflict use case. It distinguishes this tool from siblings like emacs_ediff_files and emacs_ediff_buffers by explicitly marking it as three-way and file-based.

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 a clear context: 'useful for merge conflicts', which signals when an agent should consider this tool. However, it does not explicitly exclude two-way comparisons or mention alternative tools, so while the usage context is clear, there is no explicit when-not guidance.

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 full burden of behavioral disclosure. It only says 'Compare two buffers and return the diff'; it does not state whether buffers are modified, whether an interactive Ediff session is started, or whether buffers must already exist. Given that 'ediff' in Emacs usually implies interactive behavior, this ambiguity is significant.

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 a single sentence with no wasted words and the main action is front-loaded. It is appropriately terse, though it sacrifices useful behavioral and usage context for brevity.

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?

Without an output schema or annotations, the description should at least clarify the return value's nature and any side effects. While the schema documents format and context_lines, the description does not make clear whether the result is a textual diff string or an interactive Ediff buffer, leaving a meaningful completeness gap.

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 input schema provides 100% parameter coverage, so the baseline is 3. The description adds no extra meaning for buffer_a, buffer_b, format, or context_lines beyond what the schema already documents.

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 a clear action ('Compare'), a specific resource ('two buffers'), and an outcome ('return the diff'). It is distinguishable from sibling tools like emacs_ediff_files and emacs_ediff_regions by naming buffers as the target, though it does not explicitly contrast with those alternatives.

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 emacs_ediff_files, emacs_ediff_regions, or emacs_ediff_3way. The intended scope is only implied by the tool name and the phrase 'two buffers', but no explicit when-to-use or alternative routing 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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It says the tool returns the diff, but does not disclose whether it launches an interactive Ediff session, returns plain text, requires existing files, or how format and context_lines affect execution. This is minimal disclosure.

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?

One sentence with no filler, front-loaded with the action and object, and ending with the result. Every word contributes to the tool's meaning.

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 core purpose and the returned diff are stated, and the parameter schema fills in format and context-line details. However, with no annotations and no output schema, the description leaves ambiguity about interactive versus non-interactive behavior and does not route the agent among the many diff-related siblings.

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 schema already documents file_a, file_b, format, and context_lines. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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?

Description states a clear verb ('Compare'), resource ('two files'), and result ('return the diff'), which helps distinguish it from buffer- and region-based ediff siblings. It does not explicitly contrast with emacs_git_diff or emacs_diff_summary, but the two-file scope is reasonably specific.

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?

No guidance is provided on when to choose this tool over the many diff-related siblings such as emacs_git_diff, emacs_ediff_buffers, emacs_ediff_regions, or emacs_diff_summary. Usage is only implied by the action 'Compare two files'; no exclusions or preconditions are stated.

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 full burden of behavioral disclosure. It states a read-only comparison action, but does not explicitly confirm that no state is modified, nor does it explain the shape of the returned diff, error behavior, or whether the operation is a true ediff invocation. The description is minimal and leaves these behavioral traits undisclosed.

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 a single focused sentence with no filler or repetition. It states the action, the resource, and the output in six words, which is appropriately concise and front-loaded.

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 parameter schema is complete and the core purpose is sufficiently clear for invocation. However, there is no output schema and no mention of what the returned diff looks like, how format interacts with the output, or when this tool should be preferred over sibling diff tools. It is minimally adequate but leaves notable gaps.

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 all six parameters are already documented in the input schema. The description adds no parameter-specific meaning, but the schema carries the semantic weight, so the baseline of 3 applies.

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 uses a specific verb ('compare') and resource ('two text regions') and states the result ('return the diff'). It clearly distinguishes from sibling tools that operate on files or buffers, though it does not name them explicitly.

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?

There is no guidance on when to use this tool versus emacs_ediff_files, emacs_ediff_buffers, emacs_ediff_3way, or emacs_diff_summary. No alternatives or exclusion conditions are mentioned, so the agent must infer appropriate usage from the name and description alone.

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 full burden of behavioral disclosure. It states that code is executed and the result returned, but it does not disclose that arbitrary Lisp evaluation can mutate Emacs state, run side effects, or behave dangerously based on the evaluated code.

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 one short sentence with no filler. It front-loads the main action and directly communicates the core behavior.

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 powerful arbitrary-code-execution tool, this is too thin. It omits safety warnings, error behavior, result serialization details, timeout semantics beyond the schema default, and the fact that evaluation can have persistent side effects on the Emacs environment.

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 both parameters are already documented in the schema. The description adds no additional meaning beyond saying that the code is executed and a result returned.

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 specifies a clear verb-resource pair: execute Emacs Lisp code and return the result. It is immediately distinguishable from all sibling tools, none of which perform arbitrary Lisp evaluation.

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?

No guidance is given about when to use this tool versus the many dedicated Emacs operations available among siblings. It does not state that this is for arbitrary Lisp evaluation not covered by specialized tools, nor does it warn about cases where dedicated tools would be safer.

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. 'Get information' signals a read-only operation and lists several output dimensions, but it doesn't disclose the full return shape, error behavior, or whether symlinks/directories are supported. The 'etc.' leaves unspecified behavior.

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?

One concise, front-loaded sentence with no filler. Every word contributes; the examples are useful.

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 one-parameter stat-like tool, the description is serviceable, but with no output schema it should spell out the return fields rather than ending in 'etc.' It also doesn't mention edge cases or whether it works on directories. Overall adequate but with clear gaps.

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 only parameter, path, is fully described in the schema ('File path to get info for'), so schema coverage is 100%. The description adds no extra meaning about the path beyond that, landing at the baseline 3.

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 names a specific operation ('Get information about a file') and gives concrete examples of the returned metadata (exists, readable, writable, size). It reads as distinct from sibling file operations like emacs_file_open and emacs_file_save, though it doesn't state that distinction explicitly.

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 the tool is for metadata lookups, but it gives no explicit guidance about when to choose it over alternatives (e.g., emacs_buffer_read for content, emacs_file_open for opening). There are no exclusions or routing hints.

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 full burden. 'Open a file' does not disclose what opening means behaviorally: whether it creates a buffer, switches the current buffer, requires an existing file, or returns any confirmation. This is a minimal statement of intent, not a behavioral disclosure.

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 a single sentence with no filler, but it is also under-specified and mostly echoes the tool name. It is concise in length but not particularly informative, so it does not reach the level of a genuinely helpful concise description.

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 no annotations, no output schema, and only a one-line description, the agent lacks important context: what effect opening has on Emacs state, whether the file must exist, and what the tool returns. The schema covers parameters, but the operational context is incomplete.

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 documents all three parameters with 100% coverage, so the baseline is 3. The description adds no extra meaning about path, line, or column beyond what the schema provides. It neither helps nor harms parameter understanding.

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 a clear verb-resource pair: 'Open a file in Emacs.' This is distinct from obvious siblings like save, info, or buffer operations, but it does not explicitly differentiate itself from related file/buffer tools such as emacs_buffer_switch or emacs_buffer_read.

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?

There is no guidance about when to use this tool versus alternatives. It does not mention conditions, exclusions, or compare with emacs_buffer_read, emacs_file_info, or any other sibling. The agent must infer usage solely from the tool name.

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 full burden of behavioral disclosure. It indicates a write operation but does not mention overwriting behavior, error conditions (e.g., buffer not visiting a file), or side effects like modifying the buffer's saved state. This is thin for a mutating 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 a single sentence with no wasted words, and the main scoping detail ('current or specified buffer') is front-loaded. It is appropriately sized for a tool with one optional parameter.

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 simple, with one optional parameter and no output schema, so the description covers the essential calling context. However, for a save operation with no annotations, missing details about overwrite behavior and failure cases leave it slightly incomplete.

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%, and the single 'buffer' parameter is already documented as optional with 'uses current buffer if not specified'. The description's wording 'current or specified buffer' aligns with the schema but adds no additional semantic detail, so the baseline of 3 is appropriate.

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 a specific action ('Save') and a clear resource ('the current or specified buffer to file'), so an agent knows what the tool does. It does not explicitly distinguish itself from sibling emacs_file_save_as, but the phrase 'to file' and the optional buffer parameter make the core purpose unambiguous.

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?

No guidance is provided about when to use this tool versus alternatives like emacs_file_save_as or emacs_buffer_write. The description implies a save action, but it does not state prerequisites, exclusion cases, or when the sibling save-as tool should be chosen instead.

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 of behavioral disclosure. It states the core operation but does not explain whether an existing file at the target path is overwritten, whether the buffer is renamed to visit the new path, or what side effects occur.

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 a single, well-constructed sentence with no filler or redundancy. It front-loads the action and destination clearly, earning every word.

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 tool is simple with only two documented parameters, the absence of annotations and an output schema means the description must carry more weight. It lacks important operational context such as overwrite behavior, buffer state after saving, and any error conditions, leaving the agent with meaningful uncertainty.

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%, and both parameters have meaningful descriptions in the input schema. The tool description adds little beyond the schema, so the baseline of 3 is appropriate; it does not introduce new parameter meaning or constraints.

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 uses a specific verb ('Save'), a specific resource ('buffer'), and a specific destination ('new file path'), making it immediately clear what the tool does. The phrase 'new file path' also distinguishes it from sibling emacs_file_save, which presumably saves to the current path.

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: use this when you want to save a buffer to a new file path rather than its existing location. However, it does not explicitly state when not to use it, mention prerequisites, or name alternatives such as emacs_file_save.

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 of behavioral disclosure. It only states the tool shows git blame and omits important behavioral traits such as requiring a Git repository, needing committed history, or how line ranges affect results. The read-only nature is implied but not explicitly stated.

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 and front-loaded with the action verb and resource. There is no wasted wording, though it may be terse to the point of being under-specified for a tool with optional range parameters.

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 lack of annotations and output schema, the description leaves out return format, line-range semantics, and repository preconditions. An agent would have to infer whether the tool works on uncommitted files or what the output looks like, making it incomplete for confident 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 describes all three parameters with basic meanings, and schema description coverage is 100%, so the baseline is 3. The description adds no extra semantics about how start_line and end_line interact, whether they are inclusive, or how the file path should be specified.

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 verb 'Show' and the resource 'git blame for a file', making the core purpose understandable. However, it does not explicitly differentiate this from sibling tools like emacs_git_diff or emacs_git_log beyond the blame name itself.

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?

No guidance is provided about when to use git blame versus alternatives such as git_log, git_diff, or git_status. There are no listed use cases, prerequisites, or tips that would help an agent select this tool over its siblings.

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 full burden. It merely says 'Checkout a branch' without disclosing that switching branches changes the working state, that the create parameter can make a new branch, or what happens if the branch does not exist. This is a state-changing operation, so the lack of behavioral detail is a meaningful gap.

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 a single, concise sentence with no wasted words. It is front-loaded and easy to parse, but it is under-specified—omitting the create parameter and any context—making it less useful than a slightly longer but more informative description.

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 simple (two parameters, one required) and the schema covers the parameters, so basic invocation is possible. However, the description doesn't mention the create behavior or the side effects of switching branches, and there is no output schema or additional context to fill that gap.

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 both 'branch' and 'create' are already documented in the schema. The description adds no meaning beyond restating the target branch, but with full schema coverage the baseline of 3 applies.

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 a specific verb ('Checkout') and resource ('a branch'), which clearly identifies the git checkout action. However, it doesn't differentiate from siblings like emacs_git_branch_list or emacs_git_branch_current, and doesn't mention the tool's ability to create a branch.

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?

There is no guidance on when to use this tool versus other git operations such as listing branches or viewing the current branch. The agent is given no exclusions or alternative routing cues, so it must infer usage from the tool name alone.

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 verb 'Get' implies a read-only operation with no side effects, and the description makes the purpose plain. However, with no annotations, nothing is disclosed about error behavior (e.g., outside a git repository) or how the repository is resolved.

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?

Five words, front-loaded with the action and object, no filler. Every token earns its place.

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 no-argument getter this is close to sufficient: an agent knows no inputs are needed and the output is the current branch name. But with no output schema or annotations, the description leaves 'current' repository scope implicit and says nothing about failure modes, making it minimally viable rather than 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?

The tool has zero parameters, so there are no parameter semantics to document. Baseline 4 applies because the schema is complete and there is nothing for the description to compensate for.

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?

States a specific verb 'Get' and the exact resource 'current branch name', which clearly distinguishes this from siblings like git_branch_list and git_branch_checkout. It does not spell out the repository scope, but the meaning is direct and unambiguous.

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?

No guidance on when to choose this vs git_branch_list or git_branch_checkout, nor what 'current' refers to. The intended use is inferable from the name, but the description offers no explicit context or exclusions.

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 full burden of behavioral disclosure, yet it reveals nothing beyond the tool's name: no statement about which repository/buffer context it operates in, no mention of output shape, and no confirmation of read-only behavior. 'List' weakly implies a read operation, but the description adds essentially no behavioral context.

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?

A single three-word sentence with zero padding, front-loaded with the action verb. It is efficient, though the brevity approaches under-specification rather than disciplined conciseness.

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 low-complexity tool with a fully documented single parameter, the definition is minimally adequate. However, with no annotations and no output schema, the description fails to state the operating context (current project/buffer repository) or distinguish itself from emacs_git_branch_current, leaving gaps an agent must resolve by assumption.

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% — the 'all' parameter is fully documented as 'Include remote branches (default: false)'. The description adds nothing about the parameter, but per the baseline rule for high schema coverage, a 3 is appropriate.

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 a specific verb ('List') and resource ('git branches'), giving an unambiguous statement of what the tool does. However, it does not differentiate from the sibling emacs_git_branch_current, leaving the agent to guess which branch-listing tool to pick.

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 when-to-use guidance, no exclusions, and no pointers to alternatives. With siblings like emacs_git_branch_current and emacs_git_branch_checkout nearby, an agent gets no help choosing among them. Nothing is implied beyond the bare purpose.

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 must carry the behavioral burden. It only says it creates a commit; it doesn't disclose that this mutates git history, that a commit may fail without staged changes, or what the returned output is.

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?

A single, front-loaded sentence with no filler or redundant clauses. It is appropriately concise for a tool with two parameters.

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 mutation tool with no annotations and no output schema, this is thin context. It omits the need for staged changes, the effect of 'amend', and possible failure modes, which an agent would need for robust 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%: both 'message' and 'amend' are documented in the input schema. The description adds no parameter meaning beyond restating that the commit uses a message, so the baseline of 3 is appropriate.

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 ('Create a git commit') and the required input ('with a message'), which distinguishes it from the sibling staging/status/log tools. It doesn't explicitly call out when not to use it or name alternatives, so it stops short of a 5.

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?

There is no guidance on when to use this tool versus emacs_git_stage, emacs_git_status, or others, and no mention that changes should be staged first. The description leaves the agent to infer the prerequisite workflow from context.

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 present, so the description carries the burden. The verb 'Get' suggests a read-only, side-effect-free operation, but there is no statement about output format, behavior when no changes exist, or relationship of the commit parameter. It adds only minimal behavioral context.

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?

A single front-loaded sentence communicates the core purpose with no filler. All content earns its place.

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 simple read-only query tool with full schema coverage and a required enum, the description is nearly sufficient. The main gap is no indication of what the diff output looks like, but no output schema exists and the operation is low-risk.

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?

Input schema covers all three parameters with 100% description coverage. The tool description adds no parameter-level meaning, so it neither improves nor harms the schema. Baseline 3 applies.

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?

States a specific verb ('Get') and resource ('diff') with the three supported change categories. This cleanly distinguishes from git_status and diff_summary siblings by naming the exact diff 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 'staged, unstaged, or committed' phrase gives the intended context, but the description never names sibling tools like emacs_diff_summary or emacs_ediff_* or states when not to use it. Guidance is implied rather than explicit.

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 of behavioral disclosure. It only says 'Get commit log' and does not explain how results are returned, whether an Emacs buffer is opened, whether it is read-only, or how errors are handled. This is a minimal hint at best.

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 short, but this is under-specification rather than effective conciseness. A tool with four parameters, no annotations, and no output schema needs more than a three-word phrase to be adequately specified.

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 description lacks enough context for an agent to confidently invoke the tool. It does not explain what 'commit log' means in this Emacs context, how the output is presented, whether a branch or repo is required, or how this relates to the many sibling git tools. The absence of an output schema increases the need for descriptive completeness.

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 parameters are already well-documented in the input schema. The description adds no additional parameter context, which matches the baseline expectation for fully covered schemas.

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 a specific verb ('Get') and resource ('commit log'), which clearly identifies what the tool does and distinguishes it from related git tools like status, diff, or blame. However, it does not add scope details (e.g., current repository) or explicitly differentiate from siblings, so it stops short of a 5.

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?

There is no guidance about when to use this tool versus alternatives such as emacs_git_status, emacs_git_diff, or emacs_git_blame. The description does not mention prerequisites, common workflows, or situations where this tool is preferred.

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?

There are no annotations, so the description carries the full burden of disclosing behavior. It only says it stages files; it does not state that this modifies the Git index, that the change is reversible, whether the operation fails outside a repository, or what the tool returns.

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 a single focused sentence with no padding or repetition. Every word contributes to understanding the tool's purpose.

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 low-complexity: one optional, fully documented parameter and no nested objects or enums. The description plus schema is sufficient for an agent to invoke it correctly. Return values are not described, but the lack of an output schema makes that less critical here.

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%, and the files parameter already explains its role and the empty-array-for-all semantics. The description adds no substantive meaning beyond the schema, so the baseline 3 applies.

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 'Stage file(s) for commit' contains a specific action and resource: it stages files for a Git commit. This clearly distinguishes it from siblings like emacs_git_unstage and emacs_git_commit, even without naming them.

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 no explicit when-to-use guidance and names no alternatives or exclusions. An agent must infer from the tool name and common Git workflow that staging precedes committing and that unstaging is the inverse operation.

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 verb 'List' conveys that this is a non-destructive read operation, which is useful given there are no annotations. However, the description does not disclose the output shape, whether it lists stashes for the current repository, or how it behaves when no stashes exist or when not in a git repo.

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 only three words, contains no filler, and places the core action and resource up front. Nothing could be removed without losing meaning.

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 zero-parameter, no-output-schema tool, the description is minimally adequate. However, it lacks optional but useful context such as return format, repository scope, and preconditions. The gaps are modest because the operation is simple, but they keep it from being fully 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?

The tool has zero parameters and schema description coverage is 100%, so there is no parameter documentation burden. The baseline of 4 applies because there is no ambiguity for an agent to resolve.

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 uses a specific verb ('List') and a specific resource ('git stashes'), making the operation unambiguous. It also distinguishes itself from sibling tools like emacs_git_stash_push and emacs_git_stash_pop because it is the read-only listing counterpart.

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?

There is no guidance on when to use this tool versus alternatives such as emacs_git_status, emacs_git_log, or emacs_git_stash_pop. It does not mention that stashes should be inspected before applying them or that an initialized git repository is a prerequisite.

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 full burden of behavioral disclosure. 'Pop' is a mutating operation that applies changes to the working tree and deletes the stash entry, and it can fail with merge conflicts — none of these side effects or failure modes are disclosed. The description conveys only the operation name, not its consequences or reversibility.

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?

Four words with zero filler, and the action ('Pop') is front-loaded ahead of the resource. For a single-parameter tool with complete schema coverage, this is an appropriately sized and well-structured description.

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 one optional parameter, the name, schema, and description together are nearly sufficient to invoke it correctly. However, with no output schema and no annotations, the missing side-effect disclosure and the lack of guidance on when popping is appropriate leave real gaps for a mutating operation.

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 100%; the schema already fully documents the single parameter ('Stash index to pop (default: 0)'). The description's phrase 'the latest stash' redundantly restates the default index of 0 and adds no new parameter semantics, so the baseline score of 3 applies.

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 a specific verb ('Pop') and a specific resource ('the latest stash'), and the verb clearly distinguishes it from sibling stash tools (emacs_git_stash_list, emacs_git_stash_push) and the broader git family. However, it relies on the reader knowing git semantics — it never explains that popping applies the stashed changes and removes the entry from the stash list.

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?

No guidance is given on when to use this tool versus alternatives. Siblings emacs_git_stash_list and emacs_git_stash_push exist, but the description provides no condition for choosing pop, no prerequisite (a stash must exist before popping), and no note on how the index parameter relates to the available stash list.

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 present, the description carries the full behavioral disclosure burden, but it only states that a stash is created. It does not mention that git stash push also reverts working-tree changes, how staged versus unstaged changes are treated, or any side effects on the repository state.

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 four words long and every word contributes meaning. It is front-loaded and appropriately sized for a simple operation with only two optional parameters.

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 description is minimally viable: it states the core operation and the schema fully documents the parameters. However, it lacks any broader context about the effect on the working tree or how this tool relates to the other git stash operations, which would help an agent use it more confidently.

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 100%, and both parameters already have meaningful descriptions in the input schema. The tool description adds no parameter-level information, but with full schema coverage the baseline of 3 is appropriate.

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 'Create a new stash' clearly states the verb and resource, making the tool's basic purpose unambiguous. It does not explicitly differentiate from sibling tools like emacs_git_stash_list or emacs_git_stash_pop, but the wording is specific enough to avoid confusion.

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 emacs_git_stash_pop or emacs_git_stash_list. There are no conditions, prerequisites, or exclusions stated, leaving the selection logic entirely to the agent's inference.

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 behavioral disclosure burden. The word 'Get' implies a read-only operation and the parenthetical indicates what file groups are reported, but the description does not explicitly state that the working tree is not modified or describe the output format.

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 a single sentence with no filler. The parenthetical adds useful scope information without redundancy, and the core verb and resource are front-loaded.

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 simple read-only status tool, the description plus the schema covers the essential invocation details. However, because there is no output schema, the description leaves return formatting (raw git output versus parsed file lists) implicit, so it is not fully 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?

Schema description coverage is 100%: the only parameter, repo_path, is already documented as optional and using the current directory. The tool description adds no parameter semantics beyond what the schema provides, so the baseline score applies.

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 the exact operation 'Get git status' and names the relevant file categories (staged, unstaged, untracked files). This clearly distinguishes it from sibling tools like emacs_git_diff or emacs_git_log, so an agent can identify the tool by its purpose alone.

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 emacs_git_diff, emacs_git_stage, or emacs_git_log. There is no mention of context, exclusions, or which sibling to prefer in different situations.

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 caries the full burden of behavioral disclosure, but it only restates the operation. It does not explain that unstaging affects only the index and leaves working-tree changes intact, nor does it mention whether the operation is destructive or reversible.

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 a single concise, front-loaded sentence with no wasted words. It is slightly under-specified, but structurally it is efficient and reads directly as a callable operation.

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 no annotations, no output schema, and no behavioral detail, the description is not complete enough. An agent must infer the git-index semantics and return behavior from the tool name alone, which is insufficient for correct invocation in edge 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 input schema covers 100% of the single 'files' parameter, including a description that an empty array unstages all files. The tool description adds no extra parameter meaning, which is acceptable given the high schema coverage 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 'Unstage file(s)' names a specific verb and resource, clearly identifying the operation. It also distinguishes itself from the sibling emacs_git_stage tool, so an agent can tell the two apart without opening schemas.

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 no guidance on when to use this tool versus alternatives like emacs_git_stage, emacs_git_status, or emacs_git_commit. There is no mention of workflow context, prerequisites, or conditions that should trigger the unstage operation.

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 must disclose behavior itself. It conveys only that the operation is a query and does not describe outputs, side effects, or the impact of span and filter. This is a clear gap for a tool that must be invoked autonomously.

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 text is very short and front-loaded, with no filler. However, it is closer to under-specification than to efficient completeness: one phrase carries almost no operational detail.

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 no output schema and no annotations, the description does not explain what an 'org-agenda items' query returns, how results are presented, or how span and filter shape the result. Two fully documented parameters and a simple name do not fully compensate for the missing behavioral context.

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% and the description adds no parameter meaning beyond the schema; the schema already documents span choices and filter syntax. Baseline 3 applies because the description need not repeat what structured fields already say.

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 a specific verb, 'Query', and a specific resource, 'org-agenda items', so an agent can identify this as a read-oriented agenda tool rather than an org file read/write tool. It does not explicitly distinguish it from emacs_org_search, but the resource phrase narrows scope enough.

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?

There is no guidance on when to call this tool, no exclusions, and no mention of sibling alternatives such as emacs_org_search or emacs_org_todo_list. The agent must infer usage from the generic 'Query' wording and the schema.

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 full burden of behavioral disclosure. org-capture is behaviorally distinctive: it depends on pre-configured capture templates in the user's Emacs configuration, typically appends to a target file defined by the template, and can open an interactive capture buffer requiring user action to finalize. The description discloses none of this, stating only that it 'create[s]' an entry.

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?

A single nine-word sentence with no filler. It front-loads the verb and resource and includes the distinguishing mechanism. Nothing could be removed without losing meaning.

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 has moderate behavioral complexity (org-capture semantics and configuration dependencies), with no annotations and no output schema, so the description must carry substantial weight. It is missing success behavior, prerequisites (templates must be configured), where the entry is written, and how this tool relates to sibling org tools. A single sentence is not enough for an agent to invoke this correctly and predict the outcome.

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 schema already documents all three parameters, including an example for template ('t' for todo, 'n' for note). The description adds minimal meaning beyond the schema — it reinforces that capture templates are involved but does not clarify how title/content interact with a template or whether they are optional.

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 'Create a new org entry using capture templates' names a specific verb (Create), a specific resource (org entry), and a specific mechanism (capture templates). It is clear and meaningful to anyone familiar with Emacs org-mode, but it does not explicitly differentiate itself from sibling tools like emacs_org_write or emacs_org_heading_add, which also create org content.

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 no guidance on when to use this tool versus alternatives. An agent cannot tell from the description whether to choose emacs_org_capture, emacs_org_write, or emacs_org_heading_add for a given request. The phrase 'capture templates' weakly implies the use case, but there is no explicit when/when-not guidance.

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 full behavioral disclosure burden. It does not mention that export likely writes output files, where those files go, whether existing files may be overwritten, or that async execution is possible. This is a significant transparency gap for an operation with side effects.

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 one crisp sentence with no filler and gets straight to the operation and target. It is slightly underspecified, but that is more a completeness concern than a conciseness problem.

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 four parameters, no annotations, and no output schema, the description is too thin to fully prepare an agent. Missing context includes output file behavior, default destination semantics, whether async is recommended, and failure modes for invalid buffers or formats.

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 schema already documents buffer, format, output_path, and async. The description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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 uses a specific verb ('Export') and resource ('org document'), and the operation is clearly distinct from sibling org tools like emacs_org_write or emacs_org_read. 'Various formats' is vague on its own, but the schema enum fills that gap with concrete supported formats.

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?

No guidance is given about when to use this tool versus alternatives, what prerequisites exist (e.g., buffer loaded, file saved), or when another sibling like emacs_org_write or emacs_file_save would be more appropriate. The description simply states the operation without contextual direction.

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 present, so the description carries the full burden of behavioral disclosure. It only says 'Add' and does not state that the buffer is mutated, whether insertion defaults to the end, what happens to existing content, or what the tool returns. This is a mutation tool with no safety annotations.

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 a single, efficient sentence with no filler or redundancy. It is front-loaded with the core action, though it is so minimal that it omits behavioral context that a more complete description would include.

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 mutating tool with no annotations and no output schema, the description is incomplete: it omits insertion behavior, buffer requirements, return value, and failure modes. The rich parameter schema covers field meanings but not the operational context an agent needs to use the tool 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%, so all seven parameters are already documented with meaningful text. The description itself adds no parameter-level meaning beyond naming the operation, so the baseline of 3 is appropriate.

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 uses a specific verb ('Add') and names the resource ('heading') plus the scope ('org document'). It clearly distinguishes the add operation from sibling heading_update, heading_delete, and heading_move tools.

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?

No guidance is provided about when to use this tool instead of emacs_org_write, emacs_org_heading_update, or emacs_org_capture. The description does not mention prerequisites such as the buffer being open, nor does it explain how after_heading changes insertion behavior.

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 full burden of behavioral disclosure. It states the destructive scope ('and its subtree') but does not disclose whether the buffer is modified in memory only, whether the file is automatically saved, whether the action is undoable, or how matching works.

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 a single focused sentence that communicates the primary action and scope without any filler. Every word adds value.

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 simple two-parameter delete operation, the core effect is stated, but the description omits important operational details such as how headings are matched, whether deletion is persisted, and what happens if the heading text is not found. These gaps matter for an agent invoking a destructive tool without annotations or an output schema.

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 parameters are already documented with 'Buffer name' and 'Heading text to delete.' The description does not add extra meaning about exact-match semantics, case sensitivity, or uniqueness, but the baseline of 3 applies since the schema carries the parameter documentation.

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 uses a specific verb ('Delete'), a clear resource ('a heading'), and explicitly scopes the operation to 'its subtree.' This distinguishes it from sibling heading operations like add, update, and move, and adds meaningful detail beyond the tool name alone.

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 no guidance on when to use this tool versus alternatives, such as when a heading should be edited rather than deleted, or how to handle deletion when multiple headings share the same text. There are no stated exclusions, prerequisites, or side conditions.

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?

There are no annotations, so the description must disclose behavior, but it only says 'Move a heading up, down, or change its level.' It does not mention whether the whole subtree moves, how the heading text is matched, what happens with duplicate headings, or whether promote/demote changes by exactly one level. These are significant side effects for a mutating 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 a single 9-word sentence with no filler. The action and options are front-loaded and every word earns its place, though the brevity sacrifices behavioral richness captured in other dimensions.

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 no annotations, no output schema, and a mutating operation, the description is too sparse to be fully actionable. It omits subtree behavior, heading-matching semantics, error cases, and any prerequisite about operating on an Org buffer. An agent could likely select the tool but might mispredict its actual effects.

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 buffer, heading, and direction are already documented in the schema. The description restates the direction options as 'up, down, or change its level' but adds no deeper meaning beyond what the enum and parameter descriptions provide. Baseline 3 is appropriate.

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 a clear verb ('Move') and resource ('a heading') and specifies the scope: moving up/down or changing level. It is distinguishable from sibling heading operations like add/update/delete because the action is reordering or restructuring, though it does not explicitly name any sibling for contrast.

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?

No guidance is given on when to use this tool versus alternatives like emacs_org_heading_update or emacs_buffer_edit. The name and sibling list imply it is for reordering or changing heading levels, but the description leaves selection criteria entirely implicit.

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 must carry the full burden of behavioral disclosure. It only says 'Update', which signals mutation, but it does not explain what happens to existing content when new_content is provided, whether append_content appends to the current content, what occurs if the heading text is not found, or whether changes are destructive and irreversible. The mention of 'properties' also overstates behavior not supported by the 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 short and superficially concise, but it omits essential operational details and includes an unsupported 'properties' claim, so the one sentence does not fully earn its place. It is front-loaded with the action, but brevity comes at the cost of clarity about replace-versus-append behavior.

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 this is a mutation tool with five parameters, no annotations, and no output schema, the description is too thin to allow an agent to invoke it confidently. It does not specify the effect of new_content versus append_content, error behavior for missing headings, or what the tool returns after success, all of which are important for a tool that modifies an existing org-mode heading.

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 descriptions for all five parameters, so the baseline is 3. The description itself adds little beyond restating 'title' and 'content' at a high level, and its reference to 'properties' is not backed by any schema parameter. Since schema coverage is 100%, the schema handles the parameter-documentation burden adequately.

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 ('Update an existing heading') and names the alterable aspects (title, content, or properties), which distinguishes it from sibling tools like emacs_org_heading_add, emacs_org_heading_delete, and emacs_org_heading_move. However, it claims 'properties' can be updated while the input schema provides no property parameter, introducing some ambiguity about the tool's exact capabilities.

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?

No guidance is given about when to use this tool versus alternatives such as heading_add, heading_delete, heading_move, or org_write. The phrase 'existing heading' weakly implies this is for modifying already-created headings, but there is no explicit when-to-use or when-not-to-use context.

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 disclosure burden for this mutation tool. It conveys only that a property is set, but not whether existing property values are overwritten, whether a property drawer is created if absent, what happens when the heading is not found, or whether the buffer must be saved afterward. An agent cannot anticipate side effects or failure modes.

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 single sentence `Set a property for a heading` is efficiently terse with no filler. However, the brevity borders on under-specification rather than purposeful conciseness — the structural slot that should carry usage and behavior guidance is simply empty.

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 mutating tool with four required parameters, no annotations, and no output schema, this description is incomplete. It omits the behavioral traits an agent needs (overwrite semantics, drawer creation, heading-not-found handling) and provides no routing context among the large sibling set. The schema covers parameters, but behavior and usage remain unpocumented.

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 of 3 applies; the schema already documents all four parameters (value, buffer, heading, property). The description adds no parameter-level insight such as property name format, allowed value shapes, or how the heading is matched, but it also has no gaps to compensate for.

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 a specific verb (`Set`) and resource (`a property for a heading`), which unambiguously names the operation. The term `property` helps distinguish it from siblings like emacs_org_tag_set and emacs_org_todo_set, though it does not explain what an Org property is ( a key-value pair typically stored in a property drawer ), leaving a mild knowledge gap for agents unfamiliar with Org-mode conventions.

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?

No guidance whatsoever on when to use this tool versus its many org siblings (e.g., emacs_org_heading_update, emacs_org_tag_set, emacs_org_todo_set). The description is a single sentence with no when-to-use context, no exclusions, and no mention of alternatives, so an agent must guess from the name alone.

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 behavioral burden. 'Read' clearly implies a non-mutating operation, and 'optional parsed structure' discloses a key output behavior. However, it does not explain the shape of the parsed structure, buffer assumptions, or possible errors, so some transparency gaps remain.

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 one clear, front-loaded sentence with no filler. It expresses the core read operation and the raw/parsed choice without repeating schema details.

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 simple and the schema fully documents its two parameters, so the basic call is invokable. But there is no output schema, no annotation support, and no clarification of what a 'parsed structure' looks like, leaving interpretation of the result partially underspecified.

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 both buffer and format are already documented. The description adds the word 'optional' and implies the raw default, but it does not provide materially deeper parameter semantics than the input schema.

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 uses the specific verb 'Read' and the resource 'org document content', and it adds 'optional parsed structure' to clarify the output mode. It does not explicitly contrast itself with emacs_buffer_read or emacs_org_search, but the org-specific scope and format option are enough to identify its role.

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?

No guidance is given about when to choose emacs_org_read over emacs_buffer_read or emacs_org_search. The description and schema only explain what the tool does, not when it is the right tool among many similar siblings.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. 'Search org files for text or headings' implies a read operation but does not state whether results are returned, whether the search is regex/plain text, how results are formatted, or any side effects. This is minimal behavioral information.

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 a single concise sentence with the action front-loaded. It wastes no words, though it is brief to the point of under-specifying available search types. Still, as far as structure and length, it is 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?

With no output schema, no annotations, and no description of return values or search behavior, the description is not fully self-sufficient. The input schema is well-documented, but an agent still lacks essential context about what results look like and how the search behaves across buffers, agenda, or directories.

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%, and each parameter has a description and enums where applicable, so the schema already handles parameter semantics. The description adds little beyond the schema, except the phrase 'text or headings', which partially overlaps the 'type' enum. Baseline 3 is appropriate.

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 a clear verb ('Search') and resource ('org files'), and mentions 'text or headings' as the targets, which is enough to distinguish it from many siblings like emacs_org_read or emacs_project_search. However, it omits the 'tag' and 'property' search types that appear in the type enum, so it is not fully accurate.

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?

No guidance is provided about when to use this tool versus alternatives such as emacs_project_search or emacs_org_read. The description does not state exclusions, prerequisites, or conditions, leaving the agent to infer usage solely from the tool name and schema.

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 present, the description carries the full burden of behavioral disclosure, but it only states 'Set tags' without explaining that this replaces existing tags, mutates the Org buffer, or has other side effects. The schema's tag parameter does mention 'replaces existing tags', but the description itself does not add behavioral context.

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 a single, succinct sentence with no redundant wording. It is appropriately small, but it is also somewhat too terse to carry important behavioral context, so it is not a perfect balance.

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 simple three-parameter tool with full schema documentation, the description is minimally viable. However, it would benefit from mentioning the replace-existing-tags behavior and any implications of modifying the heading, since no output schema or annotations are present.

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 all three parameters are already documented in the schema. The description adds no parameter-level meaning beyond restating the resource; this aligns with the baseline score for high schema coverage.

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 uses a specific verb ('Set') and a clear resource ('tags for a heading'), making the tool's purpose immediately obvious. It also inherently distinguishes this tool from sibling tools like emacs_org_todo_set and emacs_org_property_set, since 'tags' is a distinct resource.

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 no guidance on when to use this tool versus alternatives, such as emacs_org_todo_set or emacs_org_property_set. There are no exclusions, prerequisites, or contextual hints beyond the tool's name.

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 behavioral burden. 'List' implies a read-only operation and the scope (buffer or org files) is stated, but the description doesn't disclose possible side effects like loading files or the default org-agenda-files behavior beyond the 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?

A single well-formed sentence with no wasted words, front-loading the verb and resource. It is appropriately sized for a simple listing tool.

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 simple with two optional parameters and a full schema, but with no annotations or output schema the description should provide more context about return behavior and when to choose it over related org tools. The current description is adequate but leaves these gaps.

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 schema already documents both 'state' and 'buffer' including the org-agenda-files default. The description adds no additional parameter semantics beyond this 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 states a specific action ('List') and resource ('TODO items') with a clear scope: a single buffer or across org files. It is unambiguous, though it doesn't explicitly distinguish itself from emacs_org_agenda or emacs_org_search.

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?

There is no guidance on when to use this tool instead of siblings like emacs_org_agenda, emacs_org_search, or emacs_org_read. The description does not state conditions, exclusions, or relationships to alternatives.

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 full burden of behavioral disclosure. It only states the core action and gives no information about whether existing TODO states are overwritten, what happens if the heading is not found, whether the buffer must be visible, or what side effects occur. For a mutating tool, this is a significant transparency gap beyond the schema's parameter descriptions.

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 a single, tight sentence with no filler: 'Set TODO state for a heading.' It is front-loaded with the verb and resource. While more detail could be added, there is no redundancy or wasted wording, so it earns a strong conciseness score.

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 simple three-parameter tool with full schema coverage, the description plus schema is minimally sufficient for basic invocation. However, it lacks behavioral details such as error handling, overwrite semantics, and when to use this tool over sibling org-edit operations. With no annotations and no output schema, the description leaves some important context unaddressed.

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%, and all three parameters—state, buffer, heading—have clear descriptions. The tool description adds no additional parameter semantics beyond the schema, so the baseline score of 3 is appropriate. The schema already provides examples like TODO, DONE, and NEXT.

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 uses a specific verb and resource: 'Set TODO state for a heading.' It clearly identifies the operation and the target, distinguishing it from siblings that list todos (emacs_org_todo_list) or set other attributes (emacs_org_tag_set, emacs_org_property_set). No explicit contrast is made, but the resource is specific enough that the tool's purpose is unambiguous.

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 when to use the tool: when the agent needs to change a heading's TODO keyword. However, it does not explicitly state when to prefer this over alternatives such as emacs_org_heading_update or emacs_org_tag_set, nor does it provide any exclusion criteria. The usage context is inferred rather than stated.

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 full burden of behavioral disclosure. It does convey a destructive overwrite via 'replace', but it omits critical side effects: whether the buffer must already exist, whether unsaved changes are lost, whether saving is required for persistence, and what the tool returns.

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 a single, front-loaded phrase with no filler. It could be slightly clearer by separating 'write' and 'replace' or adding a sentence of context, but it is appropriately concise for a simple tool.

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?

Despite a fully described parameter schema, the definition lacks annotations, an output schema, and any behavioral or usage context. For a destructive mutation tool surrounded by many similar Emacs siblings, the one-line description leaves too much for the agent to infer about side effects and correct selection.

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 applies. The description adds no parameter-level detail, but the schema already documents buffer, content, and save adequately.

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 uses a specific verb ('Write/replace') and names the resource ('an org buffer'), making the core operation clear. It does not explicitly differentiate from sibling emacs_buffer_write, but the 'org' qualifier narrows the target sufficiently.

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?

No usage guidance is provided. The description does not state when to choose emacs_org_write over emacs_buffer_write, emacs_org_heading_add, or other buffer/org tools, nor does it mention any prerequisites such as the buffer needing to already exist.

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 full burden. It clearly signals a read-only operation via 'Get' and names the returned values (root, name). However, it does not disclose what happens when there is no current project or whether the tool errors or returns nulls, which is a meaningful edge-case gap for a zero-parameter 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 a single, front-loaded sentence with no filler. It communicates the action and the returned data in eight words, making it optimally concise for agent consumption.

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 simple zero-parameter getter, the description is nearly complete: it names the target ('current project') and the output fields ('root and name'). The only missing context is behavior when no current project exists, and since there is no output schema, a brief note about that edge case would improve completeness.

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 tool has zero parameters, so there are no parameter semantics to document. The schema coverage is effectively 100% and the baseline score for a no-parameter tool is 4; the description does not need to add parameter-level detail.

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 a specific verb ('Get') and resource ('current project root and name'), so the agent knows exactly what the tool returns. It is also clearly distinguishable from sibling tools like emacs_project_list, emacs_project_files, and emacs_project_switch based on the 'current project' qualifier.

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 intended use is implied by 'current project' but not made explicit. There is no mention of when to prefer this over emacs_project_list or emacs_project_switch, nor any when-not-to-use guidance. An agent can infer it is for the active project, but the description does not actively guide selection.

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, and it only states the core action. Key behaviors — whether listing is recursive or top-level only, how results are ordered, path format, and behavior when no project is active or the path is invalid — are left unstated.

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?

A single nine-word sentence with no filler; the core verb and resource are front-loaded. Every word earns its place.

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?

Despite the tool's low complexity (2 optional params, full schema coverage), there is no output schema and no annotations, so an agent cannot learn the return format, recursivity, or error behavior. The description alone is thin for a tool in a large sibling family with adjacent search/info tools.

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%: both `path` and `limit` are already well-described in the schema, so the baseline is 3. The tool description adds nothing beyond the schema — it echoes the path semantics ('current or specified project') and says nothing about `limit`.

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 uses a specific verb ('List') and resource ('files in the current or specified project'), making the core function immediately clear. It is distinguishable from siblings like emacs_project_list (lists projects) and emacs_project_search (searches), though it never explicitly names a sibling to rule out.

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 phrase 'current or specified project' implies the usage context: rely on the active project or pass an explicit root. However, there is no guidance on when to prefer this over emacs_project_search or emacs_file_info, and no exclusions or alternatives are stated.

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 behavioral burden. 'List' signals a read-only operation and the parenthetical clarifies that both project systems are covered, but the description is silent on output shape, merging/deduplication, or error cases. It is minimally transparent but not detailed.

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?

One short sentence with no filler; the key verb and resource are front-loaded, and the parenthetical adds necessary scope about supported project systems.

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 zero-parameter, read-only list tool, the description is nearly sufficient. However, with no output schema, the agent is not told whether the result is project names or paths, or how the two backends are combined, so a little more context would help.

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 tool has zero parameters, so there are no parameter semantics to document. The baseline of 4 applies; the description accurately implies an unparameterized list action.

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 uses a specific verb-resource pair ('List known projects') and adds scope ('supports both project.el and projectile'), making the action clear. It does not explicitly contrast with sibling project tools such as emacs_project_current or emacs_project_switch, so sibling differentiation is not fully explicit.

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?

There is no when-to-use guidance, no alternatives, and no conditions or exclusions. An agent must infer from the name alone that this is for enumerating available projects rather than for switching to one or inspecting the current project.

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?

There are no annotations, so the description carries the behavioral burden. It accurately conveys a read-only search operation, but it does not disclose the return format (e.g., matching file paths), whether the search is recursive, or other search behavior. It is minimally transparent but not misleading.

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 a single, front-loaded sentence with no wasted words. Every part contributes to the core purpose, making it concise and easy to parse.

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 simple with two parameters and no output schema. The description plus schema gives enough to attempt a call, but the agent is left uninformed about what the search returns and how file matching is scoped. For a read-only search tool, this is a moderate gap.

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 schema documents both parameters adequately. The description adds no extra meaning about regex syntax or path resolution, aligning with the baseline score of 3.

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 a specific action (search), a resource (files in the project), and a criterion (name pattern). This clearly distinguishes it from content-search tools like emacs_org_search and buffer-related tools. However, it does not explicitly distinguish it from emacs_project_files, a likely sibling for listing project files, so it stops short of a 5.

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 when to use this tool: when you need to find project files by their name pattern. It gives no explicit context about when not to use it or which sibling tool to prefer, such as emacs_project_files for listing all files. This leaves usage guidance to inference.

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 must carry the full burden of behavioral disclosure. It only states 'Switch to a different project' with no information about side effects, state persistence, validation of the path, or impact on buffers/workspace. This is essentially the surface-level action with no behavioral traits beyond the tautological meaning.

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 a single, front-loaded sentence with no filler words. It is concise and readable, though slightly under-specified. The structure is efficient for the information it conveys.

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 has no annotations, no output schema, and relies on a single parameter. For a state-changing operation, the description does not explain what happens after switching, whether the path must already be a known project root, or how this relates to project listing/current tools. This is inadequate for safe, correct invocation without additional context.

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 parameter 'path' is already documented as 'Project root path to switch to'. The description adds no additional meaning beyond the schema, which is acceptable at the baseline score of 3.

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 uses a specific verb ('switch') and resource ('project'), clearly stating the core action. It is not a tautology, and the input schema reinforces that it changes the active project by path. However, it does not explicitly differentiate from sibling tools like emacs_workspace_switch or emacs_project_current.

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?

No guidance is given on when to use this tool versus alternatives such as emacs_workspace_switch or emacs_project_current. The description is a bare action statement with no contextual cues, prerequisites, or exclusions, leaving the agent to infer usage entirely from the name and sibling list.

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?

There are no annotations, so the description carries full responsibility for behavioral disclosure. It only says 'create' and does not explain whether the new workspace becomes active, whether duplicate names cause errors, or what the tool returns.

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 one short sentence and leads with the action and object. It is concise, though the 'workspace/tab' phrasing could be cleaner.

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 state-changing tool with no annotations and no output schema, this minimalist description leaves essential operational context missing: activation behavior, name conflict handling, and persistence. The tool is simple, but an agent still needs more behavioral guidance to call it confidently.

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 fully describes the only parameter ('Name for the new workspace'), so per baseline the description does not need to add parameter details. It provides no extra constraints or examples, but none are required given 100% schema coverage.

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 a clear verb (Create) and resource (workspace/tab), and it is the only workspace tool with a create operation among siblings, so it can be distinguished. However, the 'workspace/tab' phrase introduces slight ambiguity about the resource type.

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?

No advice is given on when to use this tool versus workspace_switch, workspace_save, or workspace_delete. An agent must infer the usage entirely from the tool name and the minimal description.

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 behavioral burden; 'Get' conveys a read-only operation with no side effects, which is adequate for a zero-parameter getter. However, it does not disclose edge-case behavior such as what happens when no workspace/tab exists.

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 a single, front-loaded sentence with no filler. Every word contributes meaning, and nothing extraneous is included.

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 zero-parameter read-only tool with no output schema, the description is nearly complete: it identifies the resource and the result. A minor gap is the lack of detail about return formatting or behavior when no active workspace exists, but the tool's simplicity keeps this omission small.

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 tool has zero parameters, so the baseline is 4 and there is no parameter semantics burden for the description to carry. The description appropriately says nothing about inputs because there are none.

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 uses a specific verb, 'Get', and a specific resource, 'current workspace/tab name', making the tool's function immediately clear. It distinguishes itself from sibling tools like emacs_workspace_list and emacs_workspace_switch by focusing on the current workspace.

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?

No explicit guidance is given about when to use this tool versus alternatives such as emacs_workspace_list or emacs_workspace_switch. The word 'current' implies the appropriate context, but the description does not state it directly.

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 full burden for disclosing side effects. It only says 'delete', implying destructiveness, but does not state irreversibility, effects on tabs/buffers, errors for missing names, or whether deletion is idempotent. A destructive tool needs at least one caveat.

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 five words and completely front-loaded. There is no redundant or speculative content; every part directly identifies what the tool does.

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 simple one-parameter destructive operation with no nested objects or output schema, this is minimally viable: an agent can identify the action and the required input. However, it lacks context about consequences, error behavior, or any restrictions on deleting a workspace, which prevents it from being fully 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?

Input schema coverage is 100% and the single parameter is already described as 'Workspace name to delete'. The description adds only the synonym 'tad' and no extra format, constraint, or behavioral context, so it meets the baseline but does not exceed it.

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 a specific verb and resource: 'Delete a workspace/tab'. This is clear and differs from sibling tools by naming deletion rather than list/switch/create/save. It does not explicitly name an alternative, but the purpose is unambiguous.

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?

No usage guidance is provided. The description does not say when to prefer this tool over workspace_create, workspace_switch, or workspace_list, nor does it mention conditions like 'cannot deletes current workspace'. The agent must infer appropriateness from the single verb.

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 full burden. 'List all' conveys a read-only, side-effect-free operation, but it does not describe the return shape (e.g., names, order) or clarify how 'tabs' relate to workspaces.

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?

A six-word sentence containing only the essential verb, resource, and scope. Every word earns its place, with no filler or repetition.

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 zero-parameter listing tool, the definition is largely complete: an agent knows what the tool does and needs no argument details. It omits output format details, but 'List' strongly implies a list of workspace/tab names, and the absent output schema makes this gap minor.

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 tool has zero parameters and an empty input schema, so there are no parameter semantics for the description to add. The baseline score of 4 applies.

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?

States a clear verb ('List') and a specific resource ('all workspaces/tabs'). The word 'all' distinguishes it from workspace_current/switch/create/delete/save, though it does not explicitly name those alternatives.

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 phrasing implies this is the tool to call when an agent needs an enumeration of all workspaces/tabs rather than current-workspace lookup or workspace mutation. However, it provides no explicit when-to-use guidance or comparison against sibling workspace tools.

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 full burden of behavior disclosure, and 'Save workspace state' gives almost no detail. It does not mention side effects, persistence, overwrite behavior, or whether an existing workspace is mutated or a new one created.

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 a single short sentence with no wasted words and is front-loaded. It is concise, though it achieves conciseness by omitting substantive content.

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 has no parameters, no annotations, and no output schema, so the description is the only source of context. For a persistence-related operation in a large Emacs tool family, saying only 'Save workspace state' is incomplete because it does not clarify what the save produces, whether it overwrites, or when to use it.

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 tool has zero parameters and the schema coverage is 100%, so there is nothing for the description to clarify about inputs. Baseline 4 is appropriate for a valid zero-parameter tool.

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 'Save workspace state' uses a specific verb and resource, which is minimally clear, but it does not explain what 'workspace state' means or how it differs from workspace-related siblings like emacs_workspace_switch or emacs_workspace_create. It is not a tautology, but it is too vague to allow precise selection.

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?

There is no guidance about when to save, what state is included, or how this compares to related tools such as emacs_workspace_create or emacs_file_save. An agent would have to guess whether to call this before switching workspaces or after creating one.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It only states the action and selection method; it does not explain the precedence when both name and index are provided, what happens on invalid input, or what observable effect occurs after switching. There is no contradiction with annotations because none exist, but the behavioral detail is minimal.

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 a single front-loaded sentence with no filler words. It conveys the essential action and parameter types efficiently, which is appropriate for a simple tool.

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 simple switch operation with two fully documented optional parameters and no output schema, the description is nearly sufficient. However, it omits behavior for ambiguous input (both name and index), invalid workspace references, and success signaling, which an agent would benefit from knowing. No return-value explanation is required, but error and precedence conditions are unaddressed.

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 input schema already fully documents both parameters with descriptions, including that index is 0-based, so schema coverage is 100%. The description's 'by name or index' adds little beyond what the schema provides, and no additional semantics such as precedence or error behavior are introduced. Baseline 3 is appropriate.

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 uses a specific verb 'Switch to' with a clear resource, 'workspace/tab', and states the two selection methods, 'by name or index'. It is distinguishable from sibling tools like emacs_workspace_list, emacs_workspace_create, and emacs_workspace_delete, though it does not explicitly differentiate from emacs_project_switch.

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?

No guidance is provided on when to use this tool versus alternatives. The description does not mention that emacs_workspace_list could be used to discover workspace names before switching, nor does it contrast with emacs_project_switch for project-level switching. The agent is left to infer the appropriate context.

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