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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds one genuinely useful piece of context — the Termux:API dependency, implying the Termux:API app must be installed/permitted — but says nothing about failure modes when the API is absent or about return shape.

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 naming what is returned and how, with no filler. Every clause 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 zero-parameter read with no output schema, the description gives the key returned fields plus the transport (Termux:API), which is enough to call it correctly. It could go further by noting that the Termux:API companion app and permission are prerequisites and that the call fails otherwise.

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?

Zero parameters, so there is nothing for the description to disambiguate; baseline applies. No false parameter hints are introduced.

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?

Specific verb (return) plus resource (battery status) with the returned fields enumerated: percentage, charging state, temperature. It doesn't contrast itself with the closest sibling (system_info), which may also surface device-level data, 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?

Usage is only implied — an agent infers it should call this when it needs battery level or charging state. There is no explicit when-to-use / when-not, and no mention of preferring this over system_info or termux_api generically.

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?

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so safety is covered. The description adds genuinely new behavioral context the annotations lack: the dependency on the termux-api package and companion app, i.e. the condition under which the call fails. It stops short of describing the empty-clipboard case or error payload.

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?

Two short sentences, zero waste: the action first, the prerequisite second. Every clause 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 zero-parameter, annotation-rich tool with no output schema, the description covers what it does and what it depends on. The only remaining gap is what the return looks like when the clipboard is empty or the dependency is missing, which is minor given the tool's simplicity.

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 disambiguate; baseline is 4 by rule. No parameter claims are made or needed.

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 (return) and resource (current Android clipboard text), and the direction of the operation is unambiguous against the sibling clipboard_set. An agent can select it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for invocation via the stated prerequisite (termux-api package + Termux:API app), which is the main precondition an agent must check. It does not explicitly name clipboard_set as the alternative for writing, but the read/write split is self-evident from name and 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?

Annotations already declare the safety profile (not read-only, idempotent, non-destructive, open-world), so the description's real contribution is the runtime dependency on the termux-api package and app, which is genuine behavioral context an agent needs before calling. It stops short of describing failure behavior when the dependency is missing.

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?

Two short sentences, zero waste, with the action front-loaded and the prerequisite following. Nothing repeats structured data.

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 write with a complete schema and full annotation coverage, the description supplies the critical missing piece (the Termux:API dependency) and nothing more is needed since there is no output schema. Minor gap: no mention of what happens if the dependency 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?

Schema coverage is 100% and the single 'text' parameter is fully documented in the schema, so the description does not need to restate it. Baseline 3 applies since the description adds no meaning 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?

States a specific verb and resource ('Set the Android clipboard text') plus the mechanism (Termux:API), making it immediately distinguishable from the clipboard_get sibling. It falls just short of a 5 because it doesn't explicitly frame itself against that sibling or state any scope limits.

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 prerequisites ('termux-api package and Termux:API app') imply when the call will succeed, but there is no guidance on when to prefer this over alternatives such as run_command or termux_api, nor any exclusions. Usage is implied 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?

The annotations declare a non-read, non-destructive, non-idempotent mutation, and the description adds real information beyond them: directories are copied recursively, and an existing destination is protected unless overwrite=true, so the agent knows a default call fails rather than silently destroying data. It does not cover permissions, symlink handling, or error/return 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?

Two short sentences with zero filler, front-loading the core action and following with the two behavioral constraints that actually change how an agent calls it.

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?

No output schema exists, and the description does not say what a successful copy returns (path, byte count, or nothing) or how failures are surfaced. Those are minor gaps for a three-parameter filesystem operation whose safety profile and recursion behavior are otherwise covered.

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 source, destination, and overwrite (including its default) are already fully documented in the schema. The description's mention of overwrite=true reinforces the safety semantics but adds no syntax or format detail beyond the structured fields, 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?

States a specific verb and resource ("Copy a file or directory to another path") that an agent can easily distinguish from write_file or edit_file. It does not explicitly name the nearest alternative (move_path), so differentiation is inferred 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?

The description implies when the tool applies (copying a file or a whole directory tree) and gives a concrete prerequisite for overwriting. But it never contrasts with move_path or write_file, so an agent must work out for itself when copying is preferable to moving.

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?

Annotations already flag destructiveHint=true, readOnlyHint=false, and idempotentHint=false, but the description adds meaningful safety behavior beyond that: the mandatory dry-run inspection step, the required confirmation token, the hard refusal of /, and the dependence on Termux Android permissions. These are exactly the behavioral details an agent needs before invoking a destructive 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?

Three tight sentences, front-loaded with the action and followed by the safety workflow and scope limit. No repetition, no filler, and the destructive nature is stated immediately.

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 destructive filesystem tool with no output schema, this description covers what an agent needs: what gets deleted, the required safety dance, the root-path guard, and the permission model. The remaining parameter details (recursive) are fully documented in the 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 coverage is 100%, so the baseline is 3, but the description adds sequencing semantics for dry_run and confirm that the schema alone does not convey: dry_run is meant to be used first to inspect the target, and the second call must carry confirm="DELETE" rather than using dry_run. The recursive parameter is left to the schema, which is acceptable given 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?

The description opens with a specific verb and resource set ('Delete a file, symlink or directory'), immediately distinguishing it from siblings like copy_path, move_path, and mkdir. An agent knows exactly what this tool does without opening the schema.

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?

It gives an explicit two-step procedure (dry_run=true first, then confirm="DELETE") and names a hard refusal condition (root /). It doesn't mention alternatives such as move_path for non-destructive removal, so it falls short of full when/when-not/alternatives guidance, but the intended usage sequence is very clear.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is handled. The description adds non-obvious behavior the annotations do not: exact matching, the single-occurrence default that makes calls fail, and atomic writes. It does not cover file-not-found or permission errors, keeping it at 4.

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?

Three short sentences, front-loaded with the core operation, followed by the match constraint and the atomicity guarantee. Every sentence carries information an agent needs.

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 fully documented parameters, annotations and no output schema, the definition covers what to send and the key failure mode (non-unique match). It leaves out edge cases like missing files or encoding problems, so it is not quite 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 coverage is 100%, so the schema already explains each parameter. The description nonetheless adds meaning the schema lacks: the default requires a unique match, and replace_all is the escape hatch for multiple matches. That is real semantic value beyond the field docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb+resource ('Replace an exact string in a UTF-8 text file'), which is specific enough to separate it from read_file or delete_path. It stops short of naming write_file, the closest sibling, so an agent must infer that whole-file overwrites belong there.

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?

It gives one real usage rule ('old_string must occur exactly once; use replace_all to replace every occurrence'), which is genuinely helpful. But it never says when to prefer this tool over write_file or how to handle the not-found/ambiguous-match failure case, so tool-selection guidance is only implied.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real behavioral detail: symlinks are reported but not followed, and dot-entries are excluded unless show_hidden=true. It omits what happens on a nonexistent path or when max_entries is hit (silent truncation vs error), which is the remaining 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?

Three short sentences, front-loaded with what is listed and what is returned, then the two behavioral caveats. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully names the returned fields (type, size, modification time, permissions) and covers symlink and hidden-entry behavior. Truncation at max_entries and error conditions remain undisclosed, which is a modest but real omission for a listing tool.

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 essentially nothing beyond it; the show_hidden note merely restates the schema default. It gives no additional meaning for max_entries, such as whether exceeding it truncates output or errors.

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 (list) and resource (files and subdirectories) and enumerates the metadata returned, which distinguishes it from a search or stat tool. It does not explicitly contrast itself with siblings like search_files or stat_path, so an agent must infer that boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the non-recursive, metadata-returning behavior, but there is no explicit statement of when to prefer this over search_files or stat_path, and no mention of prerequisites such as the path needing to exist and be readable.

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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that parent directories are created by default — but omits what happens when the target already exists and recursive is false (error vs. success) and any permission/auth requirements.

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?

Two short sentences, zero filler, with the core action front-loaded and the notable default behavior immediately after. Nothing is wasted.

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, non-destructive, idempotent filesystem tool with full schema coverage and no output schema, the description covers what it creates and the parent-directory default. The only real gap is failure behavior when the directory already exists with recursive=false, which is a minor omission.

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 'recursive' property already documents both 'Create parents' and 'Default true', so the description largely restates structured data. It adds no format, path-style, or absolute-vs-relative 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 states a specific verb and resource ('Create a directory'), which is unambiguous against filesystem siblings like delete_path, list_dir, or write_file. It does not explicitly name or differentiate itself from any sibling, but the operation is distinct enough that an agent would not confuse it.

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 when-to-use guidance, no prerequisites (e.g., permissions), and never mentions alternatives. It does not say whether to prefer mkdir over letting write_file create parents, nor when recursive behavior should be turned off.

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?

Annotations already declare destructiveHint=true, so the safety profile is known; the description adds genuinely new behavior by disclosing the cross-filesystem copy + delete fallback. It does not say whether the copy+delete path is atomic, whether overwritten data is recoverable, or what happens on partial failure.

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?

Three short sentences, zero filler, with the core action first and the two constraint statements after it. Nothing could be removed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter mutation tool with no output schema, the description covers purpose, the overwrite gate, and the cross-filesystem fallback. Missing are failure/partial-failure behavior and return value, which matter for a destructive 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% and the schema already documents all three parameters, including overwrite's meaning and default. The description's 'existing destinations require overwrite=true' restates that rule in enforcement terms, but adds no syntax, path-format, or relative-vs-absolute detail 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?

States a specific verb and resource ('Move or rename a file or directory'), which is concrete and unambiguous. It does not explicitly distinguish itself from the neighbouring copy_path or delete_path tools, 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?

'Existing destinations require overwrite=true' gives a concrete conditional rule for a non-obvious parameter, which is real guidance. It never names an alternative tool (e.g. copy_path) or states when not to use this one, so exclusions are absent.

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?

Annotations already declare readOnly=false, idempotent=true, openWorld=true and destructive=false, so the safety profile is covered. The description adds genuinely new context: the external app dependency and the notification-permission requirement, plus the update-by-id behavior that explains the idempotent hint. It stops short of 5 only because failure modes (missing app/permission) are not described.

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?

Three short sentences with the core action front-loaded, followed by prerequisites and the id/update tip. No filler, and every sentence carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

All 8 optional parameters are schema-documented, the external dependency is disclosed, and no output schema exists so return values need not be explained. The only gap is that with zero required parameters it never says whether an empty call is valid or what a permission-denied call does, which is 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?

Schema description coverage is 100%, so every one of the 8 parameters is already documented in the schema, which sets the baseline at 3. The description's note about reusing a stable id restates what the id parameter's own description ('Notification id used for updates') already says, adding no new semantics.

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 ('Create an Android notification') plus the mechanism ('via Termux:API'), so the action is unambiguous. It does not differentiate from the closest sibling, 'toast', which is another Android-side message-display tool, 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?

'Use a stable id to update an existing notification' is a concrete usage rule, and the Termux:API app + permission prerequisite is stated. However, there is no guidance on when to prefer this over toast/vibrate, or when not to use it, so usage is implied rather than fully specified.

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?

Annotations already declare openWorldHint=true and non-readonly/non-destructive behavior, and the description adds genuinely new context: paths are resolved on-device and Android permissions still apply, which warns of possible failure outside the tool's control. It doesn't describe what a success/failure response looks like, and there is no output schema to cover that 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?

Two sentences, front-loaded with the primary URL case, then the file case, then the caveat. 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?

For a two-parameter launcher, the description plus annotations cover mechanism, scope, and permission risk adequately. It could be more complete by noting that the open happens in an external app (no return value or confirmation from the tool).

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 with examples (the 'text/plain' MIME example for content_type). The description only implies the target accept-forms already stated in the schema and adds nothing about content_type handling.

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?

Specific verb + two concrete resources: 'Open an http(s) URL in the default browser, or open a local file with Android via Termux:API.' An agent immediately knows this launches external handlers rather than reading/returning content, which separates it from read_file or run_command.

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?

It gives clear usage context by mapping each input form (http(s) URL vs. local path) to the resulting behavior, so an agent knows when this tool applies. It stops short of explicit exclusions, e.g. pointing to read_file when the goal is to inspect a file's contents rather than launch it.

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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: the directory allow-list, the security.maxReadBytes cap on large reads, and the binary/base64 requirement. What it omits is the actual consequence of hitting the cap (error vs. truncation) and the return shape.

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 short sentences, front-loaded with the verb and scope, then the binary and size caveats. No filler or redundancy; each sentence carries an actionable constraint.

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?

There is no output schema, so the description should describe the return value, and it doesn't — an agent cannot tell whether content comes back as one string, whether line numbers are embedded in the text, or how a too-large read is reported. The input side is fully covered, but for a read tool the missing return semantics are a material 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 every parameter is already documented in the schema. The description restates offsets and line numbering without adding format or edge-case detail (e.g. 1-based offsets, or interaction between limit and truncation). This is the baseline case where the schema carries the parameter burden.

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 ('Read a file ... as text') plus the scoping constraint (home, shared storage, Termux tmp). It is distinguishable from write_file/edit_file by the read framing, but it never explicitly contrasts with stat_path or list_dir, so sibling differentiation is implied 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?

Gives a concrete usage rule — binary files must be read via encoding="base64" — and a precondition that the path must be in an allowed directory. It does not say when to prefer stat_path/list_dir instead of reading content, so the exclusions are only partial.

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?

Goes well beyond the destructive/openWorld annotations: no command allow list, runs with full Termux user permissions, and non-zero exit codes come back as data rather than tool errors. The explicit statement that failures are data is exactly the kind of thing an agent cannot infer from 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?

Four tight sentences: behavior and return shape first, then the permissions caveat, then error semantics, then the alternative routing. No filler and nothing buried.

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, the description supplies the return fields (exit code, stdout, stderr, duration, truncation) and the error-handling contract. Combined with full schema coverage of the five parameters, an agent has everything needed to invoke it safely.

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 cwd, timeout_sec, env and stdin are already documented. The description only echoes cwd and timeout_sec usage without adding format or interaction detail, 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?

States a specific verb+resource (run a shell command via bash -c as the Termux user) and even enumerates the returned fields. An agent can distinguish it from read_file/write_file or terminal_* siblings without reading any schema.

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?

Explicitly routes long-running or interactive work to task_* or terminal_* tools, which is real when-to-use guidance. It does not say when to prefer file-oriented siblings (read_file, write_file, list_dir) over a raw shell command, so one gap remains.

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?

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavior: symlinks are skipped and results are capped at max_results. It stops short of saying how truncation is surfaced or how results are ordered, which matters for a capped search.

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?

Three compact sentences, no redundancy, and the core semantics are front-loaded before the secondary caveats (symlinks, result cap). Every sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 optional params, full schema coverage, and no output schema, the description covers the essential semantics an agent needs to select and call the tool. The remaining gap is the shape/ordering of returned matches, which a capped multi-mode search would ideally state.

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 every parameter including defaults is already documented in the schema, making 3 the baseline. The description only re-touches glob, query, and max_results in prose without adding format, precedence (glob vs. query), or interaction details 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?

Specific verb (recursively search) plus resource (files) and two matching modes (glob on names/paths, regex on contents), which is more precise than the title alone. It does not, however, explicitly distinguish itself from nearby siblings like list_dir or read_file, so the agent must infer the boundary.

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 'optionally a regular expression in their contents' implies the two usage modes (name-only glob vs. content grep), which is useful implied guidance. There is no explicit statement of when to prefer this over list_dir/read_file, nor any exclusion or prerequisite, so usage remains 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description's added value is the disclosure that symlinks are resolved to the real path. It says nothing about error handling for nonexistent or permission-denied paths, which is the remaining behavioral 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 front-loaded sentence that declares the operation and enumerates return fields with zero filler. Nothing could be removed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description usefully enumerates the returned fields and notes real-path resolution. It is nearly complete for a trivial one-parameter read tool; only failure-mode behavior 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?

Only one parameter and schema description coverage is 100%, with the schema itself defining "Absolute path or path relative to $HOME." The description adds no path syntax, tilde handling, or edge-case guidance beyond that, 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?

A specific verb ("Return stat information") applied to a specific resource (file, directory or symlink), plus an enumeration of the returned fields (size, permissions, timestamps, resolved real path). It does not name or distinguish itself from nearby siblings such as list_dir or read_file, 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?

Usage is only implied: the mention of "stat information" suggests metadata inspection as opposed to content reading, but there is no explicit when-to-use statement, no exclusion of list_dir/read_file, and no note about behavior on missing paths.

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the breadth of collected information, but says nothing about cost or latency (this likely shells out to many probes) or output size, which an agent planning repeated calls would want.

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 dense sentence with the returned data categories front-loaded and no filler; every clause maps to a distinct part of the response.

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, the description must carry the return-value burden and largely does by enumerating the reported categories, which is enough for an agent to know whether this tool answers its question. It does not describe the shape of the returned data, which is a minor gap for a multi-section report.

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 has zero parameters, so there is nothing for the description to document and the baseline 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?

Uses a specific verb (Return) and enumerates the exact resources reported: device model, Android version, Termux paths, CPU/memory/load, storage, network interfaces, and tool availability. This clearly separates it from narrow siblings like battery_status or terminal_attach_info, though it never names those adjacent tools 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 explicit when-to-use statement, no prerequisites, and no mention of alternatives such as battery_status for power details. A useful pre-flight-check use case is only inferable from the listed contents, not 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real value beyond them: it reads persisted metadata, meaning tasks started before a termux-mcp restart still appear — a non-obvious trait an agent would otherwise guess wrong about.

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?

Two sentences, zero waste, with the core purpose front-loaded and the persistence caveat following. Every clause carries information the agent cannot get from annotations or 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?

With annotations covering the safety profile and a 100%-covered two-parameter schema, the only remaining gap is return shape — and the description compensates by naming the returned fields, so no output schema is needed. Nothing required for a correct call is missing.

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 limit (max 500, default 50) and include_finished (default true) fully documented in the schema. The description mentions no parameter behavior beyond that, 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?

States a specific verb ('List') and resource ('background tasks') and enumerates the fields returned (state, PID, exit code, log size, paths). The resource domain is clearly distinct from siblings like terminal_list and task_output, so an agent can route without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the description establishes this is the enumeration entry point for background tasks, but never says when to prefer it over task_output (read a single task's output) or terminal_list, nor any exclusions. The restart note is behavioral context, not selection 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new context by disclosing that the result includes next_offset, enabling cheap incremental polling. Without an output schema, this return-shape hint is exactly the value the description should supply.

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?

Three short sentences, front-loaded with the core action, then mode selection, then the polling tip. No filler; every sentence adds actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the calling model (tail vs. offset, blocking via wait_ms) and hints at the return value (next_offset) despite there being no output schema. A slightly fuller explanation of chaining next_offset back into offset would make it fully self-contained, but nothing an agent needs to call it correctly 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?

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by framing offset vs. tail as two alternative read modes and linking wait_ms to the wait-for-new-output behavior. The wait_for parameter and next_offset contract are only partially spelled out (e.g., no explicit tie between offset and next_offset chaining).

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+resource ('Read a task log') and immediately names the two read modes (tail lines / byte offset), which cleanly separates it from task_start, task_stop, task_list, and terminal_read. It stops short of explicitly naming those siblings, but the resource 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?

Gives clear operational guidance: default is tail-of-log, offset for incremental reads, and 'Use wait_ms to wait for new output' for blocking/polling. No explicit when-not-to-use or named alternative, which keeps it below a 5.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is covered. The description adds valuable detail about exactly which files are removed (metadata, log, status, script) and the 'no longer running' condition, though it does not address irreversibility or permissions directly.

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 waste. It states the action and the affected artifacts immediately.

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 tool with annotations covering the safety profile and full schema coverage, the description supplies the necessary context: what is deleted and the precondition. It could optionally mention that deletion is irreversible, but the annotations and scope make it sufficiently 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?

There is one parameter ('id') and schema description coverage is 100%, so the schema already documents it. The description adds no parameter-specific syntax or constraints beyond what the schema provides, making the baseline 3 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 ('Delete') and resource ('metadata, log, status and script files of a task'), making the operation clear. It does not explicitly distinguish itself from close siblings like task_stop or delete_path, so it falls 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 phrase 'task that is no longer running' implies a precondition for use, but the description does not state when to use task_remove versus task_stop or delete_path, nor does it give explicit exclusions. Usage is only implied.

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?

Beyond the annotations, it discloses key behavior: the task is detached, returns immediately, survives termux-mcp restarts, and persists its exit code in a status file. It also warns that background tasks are non-interactive, which is important for correct invocation.

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 front-loaded with the core action and return behavior, then adds operational context and alternatives. Every sentence contributes useful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description appropriately explains the immediate return values: task id, PID and log path. It also covers lifecycle behavior, persisted exit codes, follow-up tools and the non-interactive boundary.

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 all five parameters. The description adds useful return-value context but does not meaningfully elaborate on parameter 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 states a specific verb and resource: start a detached background shell command. It also distinguishes the tool from terminal_create by calling out non-interactive use and immediate return with a task id, PID and log 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?

It clearly names related tools for follow-up actions: task_output for reading output and task_stop for termination. It also gives a useful exclusion for prompts and TUI programs via terminal_create, though it does not explicitly compare against run_command for foreground execution.

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?

Annotations already declare destructiveHint=true, so the destructive profile is known; the description adds real value on top by disclosing the escalation behavior — signal the whole process group, wait a grace period, then force SIGKILL — which is exactly the risk an agent needs to understand. It leaves out what happens to the task's record and buffered output afterwards, which keeps it from a 5.

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?

Two tight sentences that front-load the kill sequence and end with the default. Nothing is repeated and nothing is 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 destructive, non-idempotent operation with no output schema and full schema coverage, the description covers the mechanism and defaults adequately. It stops short of describing error conditions (unknown/already-exited task) or whether a follow-up task_remove is needed, which are the remaining 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 every parameter (id, signal enum, grace_ms bounds) is already documented in the schema. The description restates the SIGTERM default and the grace-period semantics but adds no new syntax or constraints beyond that, which is the baseline case for high 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 names a specific action (send a signal to the task process group, escalating to SIGKILL) on a specific resource, and the title/id make the target (a background task) unambiguous. It does not explicitly distinguish itself from task_remove or terminal_kill, but the mechanics described are distinctive enough to identify the tool.

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 explains how the stop happens but never says when to choose this over siblings like task_remove (which presumably cleans up the record) or terminal_kill (which targets terminals). There are no preconditions, no exclusions, and no mention of what to do if the task is already finished.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description usefully adds that it only returns a command string rather than executing anything, plus the terminal environment requirement. It stops short of saying what happens for an unknown or dead session, which is the remaining behavioral 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?

Two sentences, front-loaded with the return value and followed by environment guidance. No filler and nothing an agent must read past to act.

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 read-only helper with no output schema, the description tells the agent what comes back (a tmux attach command) and who should call it instead. Nothing needed to invoke it correctly is missing.

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 single 'session' parameter is fully documented in the schema at 100% coverage, so the baseline applies. The description's phrase 'for a session' adds no format, naming convention, or lookup behavior beyond what the schema already states.

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 — returns the tmux attach command for a named session — and immediately contrasts it with terminal_read/terminal_write, so an agent can separate it from its closest siblings without opening any schema.

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?

Explicitly names the condition for use (running from a Termux terminal for direct human interaction) and the condition against it (external Android apps should keep using terminal_read/terminal_write). That is a concrete when/when-not plus a named alternative.

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?

Annotations only declare the safety profile (not read-only, open-world, non-idempotent, non-destructive); the description adds real behavioral context beyond that: sessions survive termux-mcp restarts, shell defaults to $SHELL/Termux bash, and bash startup files are skipped by default with the reason given. It does not cover what happens if a session name already exists, nor whether the caller must later use terminal_kill to clean up.

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 sentences, front-loaded with purpose, then capabilities, then the shell/rc caveat, then next steps. No filler and no repetition of annotation or schema 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?

For an 8-parameter, all-optional creation tool with a nested env object and no output schema, the description covers purpose, persistence, and shell behavior well. The one notable omission is what the call returns (presumably the session name/id that terminal_write needs) and the fact that the default term-<timestamp> name makes retrieving that identifier important.

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 baseline is 3; the description earns above baseline by explaining the rationale behind use_rc (a custom .bashrc can break Enter handling) and the config-level override terminal.useShellRc, which adds meaning the one-line schema description does not convey. It does not touch cwd, env, cols, rows, or shell_args, but those are already documented in 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?

States a specific verb and resource ('Create a persistent interactive shell in tmux') and immediately scopes it to REPLs, SSH, TUI programs and prompts, which separates it from one-shot command execution siblings like run_command. It also names terminal_write and terminal_read as the follow-on tools, so the agent can place this tool in the workflow without opening a schema.

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?

Gives clear when-to-use context (persistent shell, REPLs, SSH, TUI) and explicitly routes to terminal_write/terminal_read for subsequent interaction. It does not explicitly say when NOT to use this versus run_command (e.g., for one-off commands), which is the main remaining gap.

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?

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is covered. The description adds real consequence detail beyond that: the shell and any programs running in the pane are terminated, which tells the agent the blast radius extends past the session object.

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?

Two tight sentences, keyed on the parameter name, with the destructive consequence placed immediately after the invocation rule. Nothing 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 destructive two-parameter tool with full schema coverage and no output schema, the description covers selection and effect. Minor gaps remain: whether a missing session name errors, how a nonexistent session is handled, and whether running tasks are also affected.

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 both parameters are already documented; the description adds the framing that 'session' and 'all' are alternative modes rather than combinable filters, which is meaning beyond the flat 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?

States a specific verb and resource ('Kill one terminal session by name') plus the alternate bulk mode, which cleanly distinguishes it from terminal_create, terminal_write, terminal_read and terminal_resize among the siblings.

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 two invocation modes are spelled out — name a session, or set all=true to kill everything — so an agent knows how to select behavior. It stops short of warning when not to use it (e.g. neither parameter supplied, or preferring task_stop for running tasks), so no explicit 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by disclosing the returned fields, including session state and an attach command, though it does not mention ordering or 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?

A single dense sentence that front-loads the resource and then enumerates return values. No filler or repetition; every clause contributes useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the description appropriately explains what is returned: session size, command, PID, state, and attach command. It is nearly complete for this simple read-only tool, though it omits ordering or whether all sessions are always included.

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; there are no parameter semantics to explain. The description does not need to compensate for any schema gaps.

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+resource ("List tmux-backed terminal sessions") and enumerates exactly what is returned, including size, command, PID, state, and attach command. This clearly distinguishes it from siblings like terminal_create, terminal_write, and terminal_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?

There is no explicit guidance on when to use this tool versus alternatives such as terminal_attach_info or terminal_read. The listing purpose is implied by the verb "List", but no when-to-use or when-not-to-use conditions 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?

Annotations already declare readOnly/idempotent/destructive=false, so the safety profile is covered. The description adds real behavioral detail: timeout yields expect_matched=false and timed_out=true, ANSI is stripped by default, and full_history pulls the entire tmux history. Possibly missing is pagination or capture size limits, but the core behavior is well 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?

Four dense sentences, front-loaded with the core action, then the expect semantics, then two default-behavior notes. No filler or repetition of the title.

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 8 parameters and no output schema, the description compensates by documenting the key return signals (expect_matched, timed_out) and default behaviors. Adequate for correct invocation; a note on what 'visible screen' vs lines bounds mean could add polish.

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 baseline is 3; the description goes further by explaining the expect/timeout_ms interaction and the return flags it produces, plus the real effect of ansi and full_history. This adds meaning beyond the per-parameter schema text.

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 – 'capture the visible screen and recent scrollback of a terminal session' – which clearly separates it from terminal_write, terminal_create, and file reads. It does not explicitly name a sibling or state scope boundaries, but the operation 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?

Gives concrete conditional guidance: 'Use expect with a regex to wait until a prompt or marker appears' and when to use full_history. This tells the agent when a parameter pattern applies, though it offers no explicit exclusions or alternatives (e.g. vs read_file or task_output).

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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that resizing affects the tmux window/PTY of a named session, which is useful beyond the annotations, but it does not say what happens to output or programs already running in the session, nor whether the session must already exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero filler; the core action is front-loaded and the usage hint follows. Nothing could be removed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

All parameters are documented and annotations cover safety and idempotency, so the basics are present. For a tool that mutates a live PTY, however, the description omits what happens to in-flight output or running applications and whether a nonexistent session errors, leaving it 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?

Schema description coverage is 100% and all three parameters carry both descriptions and value bounds, so the schema does the heavy lifting. The description adds no syntax, format, or defaults beyond what is already structured.

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: resizing the tmux window/PTY backing a terminal session. It is clearly distinct from sibling tools like terminal_create, terminal_write, and terminal_read. It stops short of explicitly naming how it differs from those siblings, but the action 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?

"Useful before launching TUI programs" gives an explicit, actionable usage context rather than leaving it implied. There are no exclusions or when-not-to-use conditions, and no mention of how to discover current dimensions before resizing.

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?

Goes beyond the annotations by disclosing the tmux-buffer paste default for multi-line/large text, the paste=false override, the tmux key-notation convention, and that wait_ms yields a capture in the same call. It does not say what happens on a missing/dead session or whether the call blocks, but the important write-path behavior is covered.

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 front-loaded sentences, each carrying distinct information (what it sends, paste default, key syntax, wait_ms capture). No filler or repetition of the title.

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 7-parameter mutating tool with no output schema, the description covers the main behavior paths and the capture-in-same-call return mechanism. Minor gaps remain around failure modes (invalid session) and interaction between submit and keys, but nothing needed for a correct basic call is missing.

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 baseline is 3; the description earns an extra point by adding the tmux key notation vocabulary (C-c, M-x, F1) and the auto-paste condition for multi-line/large input, which clarify how keys/paste/input interact beyond the terse schema strings.

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 (send) and resource (literal text, key names, Enter to a terminal session), which is clearly distinct from terminal_read and terminal_create. It does not explicitly contrast with run_command, the nearest sibling that also executes things in a session, so a 4 rather than 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 usage (type/paste into an existing session) and explains the paste vs literal send-keys choice, but never says when to use this instead of run_command or when to prefer terminal_read. No explicit alternatives or exclusions are named.

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?

Annotations already flag destructive/openWorld/non-idempotent, and the description adds valuable context beyond them: no shell involvement, that commands inherit full Termux:API permissions, permission-gating for SMS/location/camera/mic, and that every call is audit-logged. It doesn't state concrete side effects or rollback for destructive commands, keeping it below a 5.

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?

Front-loads the core purpose and example, then consolidates permissions/audit caveats efficiently. Slightly dense run-on sentence structure but no wasted 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?

For a raw escape-hatch tool with no output schema and full schema coverage, the description covers permissions, shell behavior, and audit logging. It leaves return-value shape unspecified, but the escape-hatch nature makes that a minor 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 coverage is 100%, so all four parameters are already documented. The description adds a concrete usage example (command='wifi-connectioninfo', args=['-i']) and reinforces that no shell expansion happens, but this is a minor supplement over 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?

States a specific verb+resource ('run any termux-* command directly') and frames it as an 'advanced escape hatch', which implicitly distinguishes it from the shell-executing run_command sibling. An agent knows exactly what this does versus the higher-level 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?

The 'advanced escape hatch' framing signals this is a fallback for cases not covered by dedicated tools, and the privacy-sensitive command list hints at when extra care is needed. It stops short of explicitly naming when to prefer system_info/run_command 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds the real behavioral detail that delivery goes through Termux:API, implying an external dependency, but says nothing about failure modes when the API app is missing or whether the call blocks.

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; every clause (action, target, mechanism) 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 trivial two-parameter side-effect tool with full schema coverage and annotations, the description is nearly sufficient. It omits the one thing an agent might need to know operationally: that it depends on the Termux:API add-on being installed and functional.

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%: both text (1-500 chars) and the short boolean default are fully documented in the schema. The description adds nothing beyond that, which is acceptable given the schema does the work, 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?

States a specific verb and resource ("Show a short toast message on the device") and names the transport (Termux:API). It does not, however, distinguish itself from close siblings like notify, vibrate, or tts_speak, which an agent could easily confuse it with.

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 a toast versus notify or tts_speak, and no mention of prerequisites (Termux:API app installed, foreground app visibility). Usage is only implied by the name and the word "short".

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false, so the description should add context the annotations cannot convey. It says nothing about whether the call blocks until speech finishes, how long a 4000-character utterance takes, that the Termux:API package must be installed, or what a failure looks like. It largely restates the title.

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. It is efficient, though the brevity shades into under-specification for a tool that produces spoken output with timing side effects.

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 schema fully documents the four parameters and there is no output schema, so the input contract is covered. What is missing is behavioral context an agent needs — blocking duration, dependency on termux-api, and whether audio plays locally only — which matters for an open-world, non-idempotent side-effecting tool.

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% — text, rate, pitch, and language each carry bounds and defaults ('Default 1', BCP-47 example 'en-US'). The description adds nothing about parameters, 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?

Names a specific verb ('Speak text aloud') and a specific resource/engine ('Android text-to-speech engine via Termux:API'), which separates it from audio-adjacent siblings like notify, toast, and vibrate. It stops just short of a 5 because it never explicitly says how it differs from those siblings or what happens to the audio.

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 and no named alternative. An agent must infer that this is for spoken output rather than toast/notify/vibrate notifications, and nothing tells it whether this is appropriate for long text, blocking callers, or repeated invocations.

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?

Annotations already declare readOnly=false, idempotent=false, destructive=false, openWorld=true, so the safety profile is covered. The description adds one piece of useful context beyond that: the dependency on Termux:API. It says nothing about blocking behavior or failure when Termux:API is unavailable.

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; the action and the controlling parameter lead the sentence.

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-optional-parameter side-effect tool with full schema coverage and a complete annotation set, this is largely sufficient. The only meaningful gap is what happens if Termux:API isn't present, which an agent might need.

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%, documenting both `duration_ms` (with min/max and default 300) and `force` (silent-mode override). The description adds no meaning beyond that, 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?

States a specific verb and resource ('Vibrate the device') plus the duration scope and the underlying mechanism (Termux:API). It is clear what the tool does, though it doesn't explicitly contrast with sibling output tools like notify or toast.

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 notify/toast/tts_speak, and no prerequisites stated (e.g. Termux:API must be installed). The agent must infer the usage context entirely.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, and the description reinforces this by flagging overwrite semantics without contradicting them. It adds genuinely non-structured context: atomic writes for overwrite mode, automatic parent directory creation, and that a small JSON summary 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?

Four short sentences with no filler, and the most important information (create/overwrite/append into an allowed directory) is front-loaded. Slightly episodic but every sentence carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema, the description covers the destructive overwrite behavior, atomicity, directory creation, and return shape. The main remaining gap is guidance on choosing it over edit_file.

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 five parameters are already documented, and the description adds only a loose reference to parent directory creation. It contributes no syntax, defaults, or edge-case behavior beyond what the schema states.

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 concrete verbs (create, overwrite, append) against a specific resource (text file) and adds a scoping constraint (inside an allowed directory). It does not differentiate from the closely related edit_file sibling, so an agent must still infer which write 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?

Usage is implied by 'create, overwrite or append' and the allowed-directory constraint, but there is no explicit when-to-use or when-not guidance. Nothing tells the agent to prefer edit_file for in-place changes or read_file/stat_path for verification.

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