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

With no annotations provided, the description must carry behavioral disclosure. The verb 'Describe' implies a read-only operation with no side effects, which is helpful. However, it does not detail what happens for unknown hosts, whether the operation is purely local, or any other behavioral nuances. It goes beyond a tautology but lacks rich context.

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

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

The description is a single, concise sentence that front-loads the verb and clearly enumerates the three types of information provided. Every word adds value, with no filler or repetition. It is ideal in length and structure.

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

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

The tool is simple with one parameter and no output schema. The description provides the key return topics (services, log path roots, connection status), which is essential. However, it omits expected response format, error behavior, or any relation to sibling tools. Given the low complexity, this is a minimally complete description but not particularly informative.

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

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

The schema has one parameter, host_alias, but provides no description, and overall schema coverage is 0%. The tool description does not mention the parameter at all, relying entirely on the parameter name. While 'host_alias' is self-explanatory, the description fails to add any semantic guidance, such as how to obtain valid aliases or whether it refers to registered host names.

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

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

The description clearly states what the tool does with a specific verb ('Describe') and enumerates the resource types covered (registered services, log path roots, connection attachment status). It is specific enough to distinguish from broader tools like 'status' or 'list_hosts', though it doesn't explicitly differentiate from the similarly named 'inspect_host'.

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

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

The description gives no guidance on when to use this tool versus alternatives like 'inspect_host' or 'status'. While the purpose is clear, there are no explicit use cases, prerequisites, or exclusions provided, leaving the agent to infer when this tool is appropriate.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It mentions 'truncated' but does not explain truncation mechanics, return format, authentication requirements, or side effects. The read-only nature is implied by 'fetch' but not explicitly stated.

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

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

The description is a single concise sentence that wastes no words. It is appropriately front-loaded, with the verb and key resource in the first few words.

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

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

Given no annotations, no output schema, and minimal description, the tool is not adequately specified. The agent lacks critical information about what 'truncated' means in practice, how parameters interact, and what the response structure is. This is insufficient for a 3-parameter 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 0%, and the description gives no explanation of the three parameters (container, max_bytes, host_alias). 'Truncated' hints at max_bytes but does not directly connect. The agent cannot infer parameter meanings from the description.

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 ('Fetch') with a well-defined resource ('remote Docker container logs') and a qualifier ('truncated'), clearly distinguishing it from sibling tools like opspilot_fetch_logs or opspilot_list_hosts. It is immediately evident what this tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, edge cases, or contrast with opspilot_fetch_logs or opspilot_docker_ps. Usage context is only implied by the tool name and purpose.

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

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

No annotations are provided, so the description carries the burden. It discloses that the operation is remote and scoped to one registered host, and 'List' implies a read-only action. It does not cover output format, error cases, or authentication 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?

The description is a single, front-loaded sentence. Every word contributes: 'List' gives the action, 'remote Docker containers' the object, and 'for one registered host' the scope.

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

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

The tool is simple (one parameter, no output schema), and the description covers the core operation and scope. It omits details like response format and failure behavior, but these are not critical for a basic list command.

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

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

The schema has 0% description coverage for host_alias, but the phrase 'for one registered host' directly explains that host_alias identifies a registered host. This compensates for the bare parameter schema.

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

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

The description uses a specific verb ('List') and resource ('remote Docker containers') with a clear scope ('for one registered host'). This distinguishes it from sibling tools like opspilot_list_hosts and opspilot_docker_logs.

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 makes clear it applies to a single registered host via 'for one registered host', giving useful context. However, it does not explicitly mention alternatives or when not to use this tool compared to siblings like opspilot_docker_logs.

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

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

With no annotations, the description carries the transparency burden. It discloses the safe truncation behavior and the directory restriction, but does not mention return format, error handling, or required authentication. Some useful behavioral context is present, but much is left undeclared.

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

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

The description is two sentences long, front-loads the core purpose, and includes a critical usage warning without any redundant filler. Every sentence provides 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?

The tool has four parameters, no output schema, and no annotations. The description is too sparse to fully guide an agent on parameter semantics, expected output, or edge cases beyond the directory restriction. It is not complete enough for reliable invocation.

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

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

The schema has 0% description coverage, and the description does not explain the individual parameters host_alias, path, service, or max_bytes. The phrase 'safe truncation' hints at max_bytes, but no parameter is explicitly mapped or clarified, leaving the agent to infer semantics from names alone.

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

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

The description clearly states the tool's function: fetching a concrete log file under a catalog log root with safe truncation. It explicitly warns against passing a directory, which distinguishes it from directory-level operations and aligns with the sibling tool opspilot_list_log_files.

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 clear usage guidance: do not pass a directory, and list files first. This implies the appropriate workflow of using a listing tool before fetching, though it does not explicitly name the alternative tool.

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?

Since no annotations are provided, the description carries the full burden. 'Get' implies a read-only action, but it does not disclose error handling, whether the request is polled or blocking, or the nature of the returned 'status'. This is minimal but sufficient for a simple status lookup, though lacking depth.

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 words, effectively conveying the core functionality. It earns its place entirely 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?

The tool is simple (one parameter, no output schema or annotations), and the description conveys the basic action. However, because no output schema exists, the description should have explained the return value format or any additional expectations, and it does not. It also does not define 'broker request' in context, leaving some ambiguity.

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 compensates by mentioning 'by request ID', clarifying that the sole parameter `request_id` identifies the broker request. Since there is only one parameter and its purpose is stated, it provides adequate semantic meaning beyond the raw 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 clearly states the tool's action ('Get the status') and resource ('broker request') with the specific identifier ('by request ID'). This distinguishes it from sibling tools focused on hosts, services, logs, and docker operations, making the purpose unambiguous.

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

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

The description implies when to use the tool (when you need a broker request's status by ID) but provides no explicit guidance on alternatives or exclusions. It doesn't mention situations where another tool like opspilot_status might be more appropriate, nor does it state any prerequisites.

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

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

With no annotations, the description carries the full burden, and it does explicitly state the operation is read-only and that facts are redacted, which signals a safe inspection. However, it omits other behavioral details such as required permissions, behavior for unknown/unregistered hosts, and the exact scope of the returned facts.

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

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

The description is a single, front-loaded sentence with no filler or redundancy. It conveys the essential action, target, and key qualifiers in six words.

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

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

For a tool with no output schema or annotations, the description is too sparse to fully guide invocation. It does not describe what the returned facts include, how they are structured, or how this tool relates to the similar-looking 'opspilot_describe_host', leaving gaps in both selection and usage.

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

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

The schema has 0% description coverage and the tool description does not explicitly explain the 'host_alias' parameter or how to obtain valid values. The phrase 'one registered host' implies the alias identifies a registered host, but it does not direct the agent to use a companion listing tool or clarify input format.

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

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

The description clearly states the tool inspects one registered host and returns read-only facts, using a specific verb ('Inspect') and resource ('registered host'). However, it does not differentiate itself from the sibling tool 'opspilot_describe_host', which likely performs a similar function.

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

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

There is no guidance on when to use this tool versus alternatives like opspilot_list_hosts or opspilot_describe_host. It does not mention any prerequisites or which sibling tools provide complementary information.

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

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

With no annotations, the description must carry the full behavioral disclosure burden. It only states the listing action, implying read-only behavior but not explicitly stating it, and provides no information on authentication, side effects, or rate 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?

The description is a single concise sentence with no redundant words, directly conveying the tool's function.

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

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

For a simple zero-parameter list operation, the description states the output content (host aliases and environment labels). However, without an output schema, the description could provide more detail about the format or any limitations, but it is minimally sufficient.

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

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

The schema has zero parameters, so the baseline is 4. The description adds some context by mentioning environment labels, but it ambiguously uses 'optional' which could be mistaken for a filter parameter rather than output content.

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

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

The description uses a specific verb 'List' and identifies the resource 'registered host aliases' with optional environment labels, clearly distinguishing it from sibling tools like describe_host or inspect_host that focus on individual host details.

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

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention that this should be used first to discover available hosts before querying details, nor does it state any 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, yet it only states that the tool lists files. It does not mention whether the operation is read-only, what output format to expect, whether recursion occurs, or any permissions or side effects.

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

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

The description is just two short sentences with the core action front-loaded. Every word earns its place, and there is no redundancy or 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?

Given the lack of annotations, output schema, and parameter descriptions, the tool is under-specified. The description covers the purpose but leaves out critical invocation details such as the role of host_alias, acceptable path formats, and what a successful response looks like.

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

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

The schema has no descriptions for the parameters, and the description does not explain the meaning of host_alias or path. The phrase 'Catalog log_paths are directories' hints that path should be a directory but does not directly map to the schema parameters.

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

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

The description uses a specific verb 'list' and identifies the resource as 'files under a catalog log root directory,' which distinguishes it from sibling tools like fetch_logs and read_file. However, the term 'catalog log root directory' is not fully defined, so precision is slightly limited.

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 instruction 'list before fetching' provides clear contextual usage, indicating this tool should be used as a precursor to fetching logs. It does not explicitly name alternative tools or state exclusions, but the workflow hint is useful.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It reveals that the tool does not expose stored values, which is helpful, but it does not clarify whether the operation is read-only, what happens if the broker is not ready, or what the output format is. The 'verify' phrasing implies a check, but details are sparse.

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

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

The description is a single, well-structured sentence that immediately states the purpose and a key behavioral constraint. It contains no filler or redundant information, maximally efficient for the content it conveys.

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

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

For a zero-parameter tool with no output schema and no annotations, the description is minimal. It covers the core purpose but omits important operational details such as the returned result, error conditions, and any prerequisites (e.g., broker location). Given the tool's simplicity, it is adequate but not complete.

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

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

The tool has zero parameters, and per the guidelines, the baseline for 0 params is 4. The description adds no parameter-specific information because there are none, but it does provide context that the tool avoids exposing values, which aligns with having no inputs. This matches the baseline.

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

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

The description clearly states the tool's function: 'Verify the broker is ready for a remote connection' with a specific verb ('Verify') and resource ('broker'). The added constraint 'without exposing stored values' distinguishes it from other tools and clarifies its safety-conscious design.

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 when you need to confirm broker readiness for remote connections without exposing sensitive data. However, it does not explicitly mention when not to use this tool or name alternative tools, leaving the decision partially to the agent's inference.

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

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

No annotations are provided, so the description carries the full burden of behavioral transparency. It discloses the allowlisting restriction and remote context, but does not state read-only guarantees, authentication needs, or error behaviors.

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

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

The description is a single sentence with no filler or repetition. It is appropriately sized for the simple read operation, though it sacrifices detail for brevity.

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

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

The tool has no output schema and no annotations, leaving the description as the only source of context. It does not explain what the tool returns, how catalog-allowlisted is enforced, or what constitutes a valid host_alias/path, making it insufficient for fully autonomous use.

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

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

The schema has two required parameters with no descriptions, and the description provides no information about host_alias or path. The parameter names are self-explanatory, so semantics must be inferred from the names alone.

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

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

The description clearly states the tool reads a remote file with an additional catalog-allowlist constraint. It distinguishes from sibling write/upload tools via the verb 'read' and the qualifier 'catalog-allowlisted'.

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

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

The description provides a clear context for reading files but does not mention when to use it over alternatives like write_file or upload_file. There are no explicit exclusions or references to sibling tools, so guidance 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?

With no annotations, the description carries the transparency burden. It discloses an important behavioral trait: this is a request for local approval, not a direct restart, and it targets a single registered service. However, it does not explain what happens after approval, whether it blocks, potential side effects, or required permissions.

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

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

The description is a single, front-loaded sentence with no wasted words. Every phrase adds value: 'Request' states the action, 'single registered service' scopes the resource, and 'for local approval' clarifies the workflow.

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

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

The tool has no output schema, no annotations, and an input schema with no parameter descriptions, so the description must compensate. It fails to cover host_alias semantics, approval workflow behavior, return values, or prerequisites, leaving significant contextual gaps.

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

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

The input schema has 0% description coverage, and the tool description adds no meaningful parameter details. 'host_alias' is never mentioned, and 'service' is only vaguely tied to 'registered service' without clarifying accepted values, formats, or relationships.

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 ('Request') and resource ('service restart') with clear scope ('single registered service') and process context ('for local approval'). This clearly distinguishes it from sibling tools like opspilot_status or opspilot_get_request, which serve different purposes.

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

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

The description implies when to use the tool—when you need to request a restart of a single registered service for local approval—but it does not explicitly state alternatives or when not to use it. There is no mention of using opspilot_status for checking status or opspilot_get_request for viewing existing requests.

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

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

No annotations are provided, so the description carries the full burden. It states the action (return status and listen address) but does not explicitly mention whether it is read-only or any other behavioral traits. Since it is a status query, the description is not misleading and adequately conveys the core behavior.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It is maximally concise while conveying the essential purpose.

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

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

For a zero-parameter, no-output-schema tool, the description is largely complete. It clarifies the tool's function, though it does not elaborate on the content or format of the status, which would be nice but not critical for such a simple 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?

The tool has zero parameters, so baseline score is 4. The description needs no parameter details, and the schema confirms no inputs are required.

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

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

The description clearly states the tool returns local broker status and listen address, with a specific verb and resource. It distinguishes from siblings like opspilot_probe_remote by specifying 'local broker', making its purpose unambiguous.

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

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

The usage is implied: to check local broker status and address. No explicit when-to-use, alternatives, or exclusions are provided, but the tool's simplicity and name make its typical usage obvious.

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

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

With no annotations, the description carries the burden of disclosing behavior. It does reveal that uploads require approval and are restricted to a catalog allowlist, which is useful. However, it omits the request lifecycle (asynchronous? how to check status?), the return value, and any side effects, leaving significant behavioral ambiguity.

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

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

The description is a single sentence that quickly communicates the core purpose. It is appropriately concise and front-loaded, though the brevity sacrifices important operational details that are penalized in other dimensions.

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

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

Given the approval workflow, three untrusted parameters, no annotations, and no output schema, the description is far too sparse. It does not explain how the request approval process works, what happens after submission, what allowed files are, or how content is interpreted, leaving the agent without enough context for reliable invocation.

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

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

Schema description coverage is 0% and the description adds no parameter explanations. The parameters host_alias, path, and content are only known by name; no meaning, format, or relationship to the approval process is provided.

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

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

The description clearly states a specific action: 'Request an approved upload' to a 'catalog-allowlisted remote file'. The verb 'request' plus the resource and allowlist constraint makes the purpose distinct from siblings like opspilot_write_file, which likely implies a direct write.

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

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

No guidance is given on when to use this tool versus alternatives such as opspilot_write_file or opspilot_get_request. The description implies an approval workflow but does not explain conditions, prerequisites, or situations where this tool is appropriate.

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

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

With no annotations, the description carries the full burden. It discloses that the write requires approval and catalog-allowlisting, which is useful, but it does not explain whether this is an asynchronous request, how approval is obtained, whether content overwrites or appends, or any permissions/side effects. The behavioral model remains largely opaque.

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

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

The description is only one sentence and contains no fluff, which is structurally efficient. However, it is so terse that it omits substantial context, so it is concise but under-specified rather than optimally balanced.

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 three required parameters, no annotations, and no output schema, this description is severely incomplete. It lacks approval workflow details, return values, error conditions, and any differentiation from sibling tools. The single qualifier 'approved' and 'catalog-allowlisted' does not meaningfully complete the picture.

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 needed to explain the parameters but does not mention host_alias, path, or content at all. The parameter names are somewhat self-explanatory, but no constraints, formats, or relationships are provided, leaving the agent to guess.

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

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

The description clearly identifies the tool as writing to a remote file and adds the important qualifier that the write must be approved and the file must be catalog-allowlisted. It distinguishes itself from read/upload siblings by emphasizing the approval requirement, though it could more explicitly contrast with opspilot_upload_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?

No explicit guidance is given on when to use this tool versus alternatives like opspilot_upload_file or opspilot_read_file. The phrase 'approved write' implies a specific approval context, but there is no clear when-to-use/when-not-to-use or prerequisite information.

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