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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured context: the call does not count against the month's usage, which is a quota/rate-limit exemption an agent cannot derive from annotations or schema. It does not contradict any annotation.

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

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

A single sentence that front-loads what is returned and appends the one caveat that matters. Nothing is repeated from the schema or annotations, and there is 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?

With an output schema present, return-field detail need not be restated, and with zero parameters there is no input surface to document. For a simple, safe, no-arg status tool the description is essentially sufficient; only explicit usage framing 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 tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. The schema is empty and fully consistent with a no-argument call, and the description correctly implies no inputs are 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?

The description states a specific resource pair: the account's OpsGate plan and its current-month tool-call usage. An agent can tell this is a read-only account introspection tool, distinct from every sibling (file ops, service control, sessions, db_query). It loses a point only because 'OpsGate plan' is mildly jargon-y and the verb 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?

Usage is implied rather than stated: an agent infers it should call this to check subscription tier or remaining quota, and the parenthetical signals it is a free/cheap call worth making. There is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives for quota questions.

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 readOnlyHint=true and destructiveHint=false for the whole tool, yet the description explicitly says reloads can be issued through it when confirm=true. Reloading Asterisk configuration is a state-changing operation, so an agent trusting the annotation would believe this tool cannot mutate anything. The description is the more accurate of the two, but the result is a definition that contradicts its own structured safety signal.

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 compact clauses with no filler, and the read-only-vs-reload split is front-loaded so an agent can classify its command immediately. The awkward line breaks and mid-sentence parenthetical slightly hurt scannability but cost no real meaning.

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

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

An output schema exists, so return values need not be described, and the key gating facts (confirm for reloads, profile must be enabled, Asterisk-only) are all present. What's missing is any statement of what confirm actually protects against or what happens on an unauthorized reload attempt.

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 0%, so the description carries the load and mostly does: it shows the shape of 'command' via concrete examples and explains that 'confirm' is the gate for reloads rather than a general flag. The gap is whether 'command' takes bare syntax or an 'asterisk -rx' prefix, and no default/behavior for confirm on read-only commands.

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 concrete verb+resource: it runs an Asterisk CLI command, with examples ('pjsip show...', 'core show channels...') that pin down the domain. It is clearly distinguished from generic siblings like run_command or service_reload by the Asterisk-specific scope, though it never names those 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?

Gives real usage conditions: read-only commands run directly, reloads require confirm=true and only when the owner enabled the Asterisk profile, and the tool only works on servers with Asterisk. That is genuine when/when-not guidance, but it never routes to the obvious alternatives (service_reload, run_command) for non-Asterisk or non-CLI cases.

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, idempotentHint=false, and openWorldHint=false. The description adds destination and timestamping context, but does not explain overwrite behavior, permissions, or whether the source file is modified.

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 communicates the core action efficiently without unnecessary wording.

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 backup tool with an output schema and annotations, the description covers the basic action and destination. It still omits timestamp format, backup naming, overwrite or error behavior, and path constraints that an agent may 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?

The single required path parameter has 0% schema description coverage. The description only implies that path refers to the file being copied, without clarifying path format, whether directories are allowed, or whether path is source versus destination.

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 operation and resource: a timestamped copy of a file into the backups folder. It does not explicitly contrast with siblings like write_file or edit_file, but the backup scope is clear enough to distinguish 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?

Provides no explicit guidance on when to use this tool versus alternatives such as write_file, edit_file, or run_command. The backup intent is implied only by the phrase 'into the backups folder'.

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, but the description adds constraints the annotations do not convey: a single statement per call, a whitelist of statement types, and that the underlying account is a read-only user. It leaves out row-cap behavior, truncation, and error semantics for rejected statements.

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; the whitelist of statement types is the most decision-relevant fact in the definition.

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?

An output schema exists so return values need not be explained, and the safety/statement constraints are covered. The one real gap is the undocumented max_rows truncation behavior.

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 0%, so the description must carry parameter meaning. It partly explains the 'sql' parameter via 'One statement' and the allowed statement types, but says nothing about 'max_rows' or its default of 100, leaving the row-limit behavior completely undocumented.

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 the resource (MySQL/MariaDB) and enumerates the exact statement types permitted (SELECT/SHOW/DESCRIBE/EXPLAIN), so an agent knows precisely what the tool executes. It stops short of naming it as the only database sibling, but the surrounding siblings are filesystem/service tools, making overlap unlikely.

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 implies when-not-to-use by restricting to read statements under a read-only user, and the 'One ... statement' phrasing rules out batched SQL. There is no explicit guidance about when to choose this over, say, read_file or run_command for data inspection, nor about what happens when a write statement is submitted.

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 readOnlyHint=false, so the safety profile is known; the description still adds real context beyond them: the default is a non-mutating dry-run that returns a diff, and a backup is taken before the write. It leaves open what happens when the snippet is not unique (error vs. abort) and where the backup lives.

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 and the dry-run default front-loaded before the backup note. 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?

An output schema exists, so the diff/return shape needs no explanation, and annotations cover the destructive profile. The remaining gap is failure behavior on a non-unique snippet and backup recoverability, which matters for a destructive edit tool but is partially offset by "Backs up first."

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 0%, so the description carries the burden and does explain the critical `confirm` flag plus the uniqueness constraint on `old`. However `path` is never addressed (file vs. directory, relative vs. absolute) and `new` semantics are only implied, leaving half the parameters unelaborated.

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?

"Replace one unique snippet of a file" names a specific verb and resource and implicitly separates this from the sibling write_file (whole-file write) by scoping it to a single snippet. It stops short of naming the sibling or stating the uniqueness failure mode explicitly, so an 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 sentence "Without confirm=true it only returns the diff" gives an actionable workflow: call without confirm to preview, then call with confirm to apply. There is no explicit exclusion or comparison against write_file for full-file rewrites, which keeps it from 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations: depth is limited to 1-4, the directory must be 'allowed', and protected files are shown but marked '[protected]'.

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

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

The description is a single, front-loaded sentence with no wasted words. Both the depth constraint and protected-file behavior are stated compactly.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description covers the key non-obvious behavior—depth limits and protected files—though it leaves path semantics and usage relative to siblings implicit.

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 0%, so the description must compensate. It states the depth range 1-4, which is helpful, but does not explain the default depth or the path format beyond saying it is an 'allowed directory'.

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

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

The description uses the specific verb 'List' with the resource 'directory' and adds a depth range, making the purpose immediately clear. It does not explicitly distinguish this tool from sibling tools like search_files, but the directory-specific scope is clear enough.

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

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

The description provides no guidance on when to use list_dir versus search_files, read_file, or other filesystem siblings. It implies directory listing but offers no explicit alternatives or exclusions.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so safety is covered by structured data. The description adds nothing beyond that — no indication of what is returned, whether sessions are live processes or stored records, or how the list is scoped; the word "Open" only adds ambiguity about whether anything is being opened.

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

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

The single fragment is short but under-specified rather than concise — it spends its three words without conveying the listing behavior that the name implies. Brevity here costs comprehension instead of saving 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?

An output schema exists, so return values need not be explained, and the annotations fully cover the safety profile. Even so, for a tool sitting among start_session, read_session, stop_session, and stop/restart siblings, the description does not establish enough to select it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter meaning to add and the baseline of 4 applies. The description does not misuse or misdescribe any inputs.

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?

"Open process sessions" supplies a verb and a resource, but the verb is wrong for a tool named list_sessions and reads as a tautology-of-sorts rather than a listing operation. An agent cannot tell from this sentence whether it enumerates sessions or opens one, and it is not distinguished from start_session, read_session, or stop_session.

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 at all: no statement of what a "session" is here, no prerequisite, and no pointer to start_session/read_session/stop_session as the alternatives for acting on a single session. The agent must infer usage entirely from the tool name.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds two pieces of genuinely new behavior: access is limited to an allowlist ('allowed' file), and secret values are redacted as '***' in the output. It does not say what happens when the file is longer than the requested chunk beyond the offset hint.

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, front-loaded with the core action and no filler. The parenthetical about offset units is efficient, though 'allowed' is left unexplained and costs a little clarity.

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?

An output schema exists, so return shape need not be described. However, for a chunked reader the description omits whether truncation or end-of-file is signalled and what max_lines defaults to, which are the details an agent needs to page through a file correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the parameter meaning. It explains offset as being measured in lines, but says nothing about the units or defaults of max_lines (300) or what qualifies as a valid path, leaving two of three parameters undocumented anywhere.

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 text file) plus the operating mode (in chunks, offset in lines) and a scope constraint (allowed files). It is clear enough to call, though it does not name how it differs from siblings like search_files or tail_log.

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 or when-not-to-use guidance. With siblings such as tail_log, search_files, and list_dir in the toolbox, the description never says which one to pick for reading versus tailing versus searching a file.

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, non-destructive, closed-world and idempotent, so the safety profile is covered; the description's contribution is the cursor-like behaviour (only output produced since the previous read). That is genuinely useful context, but it omits blocking/timeout semantics and what happens when the session has ended. There is also a latent tension worth surfacing: a cursor-advancing read is not strictly idempotent, which sits awkwardly with idempotentHint=true.

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

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

A single short sentence with no filler, which is good, but here brevity costs clarity: the fragment lacks a verb and front-loads an adjective phrase rather than the action. It is under-specified rather than efficiently concise.

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

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

An output schema exists, so return values need not be explained, but the description still leaves critical gaps for a stateful polling tool: the meaning of 'wait', whether the call blocks, session lifecycle prerequisites, and behaviour on an exhausted or terminated session. For a two-parameter streaming-read tool it does too little of the work.

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 0% for both parameters, so the description must compensate and largely fails. It implies that session_id refers to a session but says nothing about its form, and the 'wait' parameter — which looks like a poll/block duration defaulting to 2 — is completely unaddressed despite being the main source of invocation ambiguity.

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 fragment "New output of a session since the last read" conveys the resource (a session) and the incremental-read semantics, but never states a verb and reads as a noun phrase. It does implicitly distinguish itself from start_session/stop_session/list_sessions by signalling delta-reading, yet the phrasing is ambiguous enough that an agent could misread it as fetching session metadata.

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 guidance, no statement of prerequisites (must a session be started first?), and no routing against the many siblings such as list_sessions or tail_log. The only usage signal is the implied "call this repeatedly to poll for new output", which the agent must infer.

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, but the description adds genuinely new behavioral context: commands are drawn from an allow-list, shell metacharacters (| ; > *) are not interpreted, path arguments are sandboxed to allowed folders, and mutations gate on confirm=true. It stops short of saying what happens when confirm is omitted on a mutating command (error vs silent skip) or how the allow-list is scoped.

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 compact sentences with the execution model front-loaded and the confirm rule last where it matters most for a destructive tool. The parenthetical example list is efficient; only minor whitespace/formatting noise detracts.

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?

An output schema exists so return values need no explanation, and the safety story is well covered. However, for a destructive, 4-parameter tool with zero schema descriptions, the missing `timeout` semantics and `cwd` meaning leave gaps an agent would have to guess at.

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 0%, so the description must carry parameter meaning. It explains `command` (allow-listed only) and `confirm` (required for cp/mv/git pull style operations), but says nothing about `cwd` as a parameter or about `timeout`, leaving two of four parameters undocumented anywhere.

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 ("Run an allow-listed command") plus the execution model (no shell interpretation). This separates it from read-only siblings like read_file and from specialized executors like asterisk_cli or db_query, though no sibling is named 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?

Gives concrete preconditions for invocation: path arguments must be inside allowed folders and mutating commands (cp, mv, git pull) require confirm=true. These are constraints rather than when-to-use-vs-alternative guidance, so an agent still has to infer that arbitrary shell scripting is impossible and which tool to pick for non-allow-listed work.

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 already establish that this is a safe, read-only, idempotent operation. The description adds useful behavior by stating it is recursive and skips protected files, but it does not explain result limiting or what happens when max_results is reached.

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

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

The description is a single front-loaded sentence with no unnecessary wording. It efficiently conveys the core operation and two important scope constraints.

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 annotations cover safety and an output schema exists, so return details are not needed in the description. However, for a four-parameter tool with no schema descriptions, the definition should explain glob and max_results more clearly.

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?

With 0% schema description coverage, the description must carry parameter meaning. It clarifies that pattern is a regular expression and path is an allowed path, but leaves glob and max_results completely unexplained.

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

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

The description uses a specific verb and resource: searching a regular expression in files. It also clarifies scope with 'recursive' and 'skips protected files,' making the operation distinct from siblings like list_dir and read_file.

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

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

The description provides no explicit when-to-use guidance or alternatives. It mentions the path must be allowed, but that is a constraint rather than usage guidance for choosing this tool over run_command or read_file.

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 covered structurally. The description adds genuinely new behavioral detail beyond that: the exact signal (HUP) and that it targets the service's main process. It still doesn't say what a service does with HUP if it has no handler, or whether the call verifies the reload succeeded.

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

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

A single sentence that front-loads the action and mechanism, then parenthetically adds examples and the precondition. No filler, nothing repeated from the schema.

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

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

An output schema exists so return values need no explanation, and the confirm precondition is stated. For a destructive, non-idempotent operation on a named target, though, the description leaves the identifier format and the failure/confirmation behavior undefined.

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 0%, so the description must carry parameter meaning. It does explain that confirm must be true, which the bare boolean schema does not convey as a requirement, but it says nothing about the required 'name' parameter (systemd unit name? container name? display name?) or what a failed/missing confirm produces.

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 action and mechanism: 'Send HUP to a service's main process' with the qualifier 'graceful reload' and concrete examples (gunicorn/nginx). This implicitly separates it from the sibling service_restart (graceful signal vs. full restart), though it never names that sibling explicitly.

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

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

The parenthetical 'graceful reload' plus the confirm=true requirement implies when to choose this over service_restart, and the confirm gate signals a potentially disruptive operation. However, it never states the exclusion rule directly ('use service_restart instead when X') or what happens for services that don't handle HUP.

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 and non-idempotent, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the confirm=true gate and the owner's sudo authorization requirement, both of which affect whether a call will succeed.

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 verb and resource come first, with preconditions in parentheses where they belong.

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?

An output schema exists, so return values need not be explained, and the auth/confirm requirements are covered. However, for a destructive operation on a live system it omits the consequence of restarting (service downtime, dropped connections) and the expected format of the service name.

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 0%, so the description must carry parameter meaning. It explains that confirm must be true, which is useful, but says nothing about the required 'name' parameter (e.g., whether it needs a .service suffix or unit-name format), leaving the required argument underspecified.

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: 'Restart a systemd service'. This clearly separates it from siblings like service_status (read) and service_reload (reload config without full restart), though it does not name those alternatives 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?

Usage is only implied via the stated precondition (confirm=true plus sudo authorization). There is no explicit guidance on when to choose restart over service_reload, or when a restart is inappropriate (e.g., production services with active connections).

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 that the call surfaces boot-time state plus journal lines, which is genuinely useful context, but it says nothing about how many journal lines are returned, whether elevated privileges are needed to read the journal, or what happens when the unit name does not 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?

One compact sentence with the resource first and the returned signals front-loaded in a parenthetical. No filler, no redundancy.

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

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

An output schema exists, so the description is not obliged to explain return values, and the safety annotations cover the read-only nature. The remaining material gap is unit-name format for the only parameter, plus unspecified journal window size, which leaves the agent guessing on a simple but real detail.

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 0% and the single required parameter 'name' is undocumented in both schema and description. It is ambiguous whether the caller should pass 'nginx' or 'nginx.service', and nothing indicates whether a unit template or instance format is accepted.

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 ('Status of') and resource ('a systemd service'), and the parenthetical specifies exactly which signals are reported (is-active plus recent journal lines). This clearly separates it from siblings like service_restart, service_reload, and tail_log, though it does not call those siblings out by name.

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 can infer this is the diagnostic step before service_restart or service_reload, but the description never says when to prefer it over tail_log or asterisk_cli, nor does it state prerequisites or exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=false. The description adds real context beyond them: commands must be allow-listed, execution is asynchronous, and output is retrieved via read_session. It omits the important behaviors though — what happens when a command is rejected by the allow-list, whether the session persists, and that stop_session governs its lifecycle.

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 compact sentence, front-loaded with the action and followed by the essential follow-up step. No filler, no repetition of the tool name.

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?

An output schema exists, so return values need not be explained. But for a destructive, non-idempotent launch tool with zero-described parameters, the definition leaves too much open: the confirm gate, allow-list failure behavior, and session cleanup are all unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across three parameters, and the description adds no meaning for any of them. The 'confirm' boolean is especially consequential on a tool flagged destructive, and neither the schema nor the description explains when it must be set or what 'cwd' defaults to.

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 plus resource ('Start an allow-listed command') and adds the key execution mode ('in the background'), which implicitly separates it from the foreground run_command sibling. It doesn't name run_command explicitly, so the 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?

It gives a useful follow-up pointer ('read its output with read_session'), so the agent knows the next step in the workflow. However, it never says when to prefer this over run_command, nor when not to use it, leaving the choice between foreground and background execution to inference.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent operation, so the safety profile is supplied structurally. The description adds nothing beyond that: it does not say whether the stop is graceful or forced, whether in-flight work is discarded, whether the session record or its history survives, or what happens on a second call given idempotentHint=false.

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 technically concise with zero redundant wording, but this is under-specification rather than economy: three words carry none of the information an agent needs. Nothing is front-loaded beyond a restatement of the name.

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?

An output schema exists, so return values need not be described. But for a mutating lifecycle tool whose one parameter is entirely undocumented, the definition leaves critical gaps: effect on the session, recoverability, and error conditions are all unstated.

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 0% for the single required parameter, so the description carries the full burden of explaining session_id — and it says nothing. It does not indicate the identifier's format or that it likely comes from list_sessions/start_session.

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?

"Stop a session" names a verb and a resource, so the basic purpose is inferable. However, it gives no scope or boundary: it does not distinguish itself from siblings like start_session, read_session, list_sessions, or the superficially similar service_restart/service_reload, and leaves ambiguous what a "session" is (shell session, agent session, DB session).

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

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

There is no when-to-use guidance, no prerequisites, and no pointers to alternatives or to how to obtain a valid session_id. The agent must infer everything from the tool name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered structurally. The description adds a genuinely useful sandbox constraint (paths must live under allowed log folders, default /var/log), but says nothing about what happens on a rejected path, whether the default folder is configurable, or any size/line limits.

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

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

A single sentence with the action, the count, the resource and the scope constraint all front-loaded. Nothing is wasted and nothing is 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 an output schema present, return values need no explanation, and the read-only/idempotent annotations cover the safety side. What remains thin is the constraint mechanics: which folders count as "allowed", what error surfaces for a disallowed path, and whether lines is capped. Adequate for a two-parameter read tool but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the load: it clarifies that "path" is a log file within allowed folders and that "lines" is the tail count. It adds no format guidance (absolute vs relative paths), no upper bound on lines, and does not explain that /var/log is a default location rather than a parameter value.

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

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

The description states a specific action and resource ("Last N lines of a log file") plus a scoping constraint ("under the allowed log folders"), which clearly separates it from generic readers like read_file or write_file. It stops short of naming a sibling alternative, so it falls just below the top mark.

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 by the word "tail" — an agent can infer this is for inspecting recent log output, but the description never says when to prefer it over read_file or search_files, nor what to do when a path falls outside the allowed folders. No exclusions or alternatives are stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds genuinely new behavior not in annotations: a dry-run diff mode gated on confirm, an automatic backup before writing, and a path allowlist restriction. It leaves open whether the backup happens during a preview-only call and whether an existing file is overwritten.

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 action and scope, with the most consequential detail (confirm gate) stated before the secondary backup note. The telegraphic 'Backs up first.' is slightly clipped but wastes no space.

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?

An output schema exists, so return values need not be described, and the destructive-write safety story is partly covered. However, for a destructive filesystem mutation the description omits whether existing content is replaced, where the backup lands, and whether the path allowlist failure mode is an error or a silent miss.

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 0%, so the description must carry parameter meaning. It explains confirm well (gates the actual write vs. a diff preview) and hints at path constraints via 'allowed paths', but content is never described and the path allowlist rules are not spelled out.

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 ('Write a file') plus a scope constraint ('in allowed paths'), which is more than a restatement of the name. It does not differentiate from the sibling edit_file, so an agent must still infer whether to overwrite wholesale or make targeted edits.

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 clause 'Without confirm=true it only returns the diff' gives real invocation guidance: call without confirm to preview, with confirm to commit. There is no statement of when to prefer this over edit_file, nor any note about prerequisites for the target path, so guidance is implied rather than explicit.

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