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

No annotations are provided, so the description carries the full behavioral burden, and it says nothing beyond the bare act of creation. It omits whether an existing trigger causes an error or an overwrite, which file is written by default, and whether the change is reversible or persisted.

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 phrase is front-loaded and free of filler, which is good. However, for a mutation tool with no annotations, using only four words leaves it under-specified rather than genuinely concise.

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?

A mutation tool with no annotations and no output schema needs the description to cover behavior, side effects, and error conditions, and this one covers none of them. An agent cannot tell what happens on duplicate triggers or how the new match is persisted.

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 schema itself documents the trigger, replacement text, target file, and vars semantics, so the description need not repeat them. The description adds no extra meaning beyond the schema, making the 3 baseline 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 ('Create') and resource ('text expansion'), which maps cleanly onto create_match and distinguishes it from sibling mutation tools like update_match and delete_match. It does not name any sibling explicitly to sharpen the boundary, 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 update_match or delete_match, and no prerequisites or conditions are stated. The agent must infer that 'create' means new entries only, with nothing about how an existing trigger is handled.

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 burden, and it discloses nothing beyond the bare verb. It does not say the deletion is irreversible, whether it requires the file to be loaded or a confirmation, or what a successful response looks like — significant gaps for a destructive mutation.

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 zero filler, which is structurally efficient. It is terse to the point of under-specification, but that gap is accounted for under contextual completeness rather than penalized twice here.

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 two-required-parameter destructive tool with no annotations and no output schema, the description omits everything an agent needs to invoke it safely: irreversibility, permission requirements, and error behavior. It is far too thin for the complexity of the 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%, with 'file' and 'trigger' both documented inline, so the schema already does the heavy lifting. The description adds no mapping between its 'text expansion' phrasing and the file/trigger parameters, so it neither helps nor hurts beyond the 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?

States a specific verb (Delete) and resource (a text expansion), which is enough for an agent to distinguish it from create_match, update_match, and list_matches. It loses a point only because it uses 'text expansion' rather than the 'match' terminology of the tool name and siblings, forcing a small inference.

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 mention of prerequisites (e.g., that a match must exist first), and no routing to alternatives such as update_match for modifying rather than removing. The agent must infer usage entirely from the 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, yet it omits key traits: whether it writes files to disk, what format the generated documentation takes, whether existing files at output_path are overwritten, and what happens on failure. For an operation with filesystem side effects, this is a substantial 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?

A single sentence with zero waste, front-loading the action and the resource before the scope qualifier. Nothing is redundant or padded.

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 two-parameter tool with no annotations and no output schema, the description is minimally adequate for selection but thin on behavior. It should at least note that it writes files and roughly what the output looks like.

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's mention of 'specific file or all files' mirrors the schema's optional-file semantics without adding format or path syntax detail, so 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+resource ('Generate documentation for Espanso commands') and states the scope ('a specific file or all files'). It is clear what the tool produces, though it makes no explicit reference to how it differs from siblings like list_matches or get_config_info.

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, nor any prerequisites or exclusions. The only usage hint ('specific file or all files') merely restates the optional-parameter behavior already in 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 behavioral burden. 'Get' implies a read, but the description does not disclose what is returned, whether it reads from disk, or whether any auth/environment setup is required.

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 wasted words. It is appropriately sized, though it is minimal rather than rich.

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 tool with no output schema, the agent still lacks any sense of what 'configuration information' contains or its format. Adequate minimum viability but leaves a real 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 tool takes zero parameters, so there is nothing for the description to clarify; the baseline of 4 applies. No parameter meaning is missing.

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 ('Get') and resource ('Espanso configuration information'), so the agent knows it's a read of config data. However, it doesn't specify what configuration information (paths, match settings, version), and the siblings are all match/documentation tools, so there's no explicit differentiation need but also no added specificity.

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 use this versus the sibling tools (list_matches, list_match_files, etc.). The description does not state prerequisites, expected 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 disclosure burden. It implies a read operation via 'List', but says nothing about pagination, ordering, result limits, or what a match record contains. For a bare listing tool this is thin.

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 efficient sentence with the resource and scope front-loaded. No wasted words, though it is arguably too terse to carry the tool's full semantics.

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, annotation-free, output-schema-free listing tool, the description covers what and scope. It still omits return shape and pagination behavior, which an agent would need 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?

Schema description coverage is 100% and the single 'file' parameter is documented there as optional. The description restates the same optional-scope idea without adding format, path, or matching semantics beyond the schema 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?

Clear verb ('List') and resource ('text expansions') with the scope stated: a specific file or all files. It distinguishes itself from the sibling list_match_files by referring to expansions rather than files, though it doesn't explicitly name that 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 on when to use this versus list_match_files, get_config_info, or any other sibling. The optional file scope is mentioned but framed as behavior, not as a decision rule. An agent must infer the usage 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, the description carries the full burden and provides none: it does not say whether the operation is read-only (implied by 'List' but undeclared), what the result contains (file paths? names?), whether files are filtered by scope or config, or how directories are handled.

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 repetition. It is not padded, though it is also arguably too short to carry the context the missing annotations leave uncovered.

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 tool this is minimally adequate, but with no output schema the description should indicate what is returned and how it differs from list_matches. The key routing information an agent needs is absent.

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 takes zero parameters, so there are no semantics to explain; baseline 4 applies. The description correctly avoids inventing parameters that don't exist.

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 and resource: 'List ... Espanso match files'. It is distinguishable from most siblings, though the distinction from list_matches (files vs. matches) is left for the agent to infer rather than stated.

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 when-to-use guidance, no conditions, and no mention of the obvious alternative list_matches. An agent must guess whether this is a discovery call, a prerequisite for get_config_info, or an alternative to list_matches.

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, and it discloses almost nothing: no note on whether the update is partial or full, what happens if the new trigger collides with an existing one, or whether the original trigger is preserved. Only the bare fact of mutation is conveyed.

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 short sentence is economical, but here the brevity is under-specification rather than disciplined conciseness — there is no front-loaded scope, precondition, or effect statement to earn credit above baseline.

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 4-parameter mutation tool with no annotations and no output schema, the description is far too thin. It should at minimum indicate the partial-update semantics implied by the optional newReplace/newTrigger fields and the identity role of trigger.

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 (file, trigger, newReplace, newTrigger) is documented in the schema itself, so the baseline is 3. The description adds no extra meaning, such as whether newTrigger renames in place or whether omitting newReplace leaves the replacement unchanged.

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 ("Update") and resource ("an existing text expansion"), which cleanly separates it from create_match, delete_match, and list_matches. It does not explicitly name or contrast with any sibling, 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 versus create_match (e.g., to rename an existing trigger) or what preconditions apply. The agent must infer usage entirely from the verb.

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