WebSlop

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It discloses that the tool returns login status and is a check operation (implying non-destructive), but does not detail polling behavior, rate limits, or possible return values, which would add context beyond the obvious.

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

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

Two sentences, front-loaded with the main purpose, and zero wasted words. It efficiently conveys what the tool does and when to call 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?

For a simple one-parameter tool with no output schema, the description provides the essential context: what it checks, when to call it, and what it returns. It could mention return value types or possible statuses, but the current level is adequate for a straightforward polling 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 input schema covers 100% of parameters, with the 'code' property described as 'The 6-digit device code from login.' The description adds no extra semantic information about the parameter, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Check') and a clear resource ('device login code'), making it distinct from sibling tools like 'login' (which initiates login) and 'get_app_status' (which checks app status). The scope is unambiguous.

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

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

The description explicitly says 'Call this after the user enters the code on the website,' providing clear timing for when to use it. It doesn't mention exclusions or alternatives, but for a simple polling tool the context is sufficient.

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. It discloses useful behavior beyond the tool's name: the app starts immediately and is accessible at {subdomain}.bonto.run. However, it does not mention prerequisites like authentication, error cases, or potential side effects (e.g., resource usage), leaving some transparency gaps.

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 with no unnecessary words. It front-loads the action ('Create a new Bonto app') and immediately gives two key behavioral facts (starts running, accessible at URL). Every word earns its place.

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

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

For a simple two-parameter tool with no output schema, the description covers the core workflow: creation, immediate execution, and the resulting access URL. It lacks mention of login requirements or failure modes, but given the tool's simplicity and schema coverage, this is a minor gap.

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

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

The input schema already provides full descriptions for both parameters (name and subdomain), so schema coverage is 100%. The description adds a small semantic boost by embedding the subdomain in the URL template, reinforcing its purpose, but does not go beyond that 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 with a specific verb and resource: 'Create a new Bonto app.' It also adds a distinctive detail by mentioning the app starts running immediately and is accessible at a subdomain URL. This distinguishes it from sibling tools like update_app, delete_app, and start_app.

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 context: it is for creating a new app. The immediate start behavior implies this is the tool to use when you want a running app from scratch. However, it does not explicitly mention alternatives or exclusions, so it stops short of 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses one key non-obvious behavior: parent directories are created automatically. However, it does not mention security/permissions, what happens if the directory already exists, or whether the operation is reversible. This is useful but incomplete.

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-loaded with the primary purpose and a key behavioral detail. Every word earns its place, with no fluff or repetition of schema information. It is extremely concise and well-structured.

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 tool with two parameters and no output schema, the description is adequate. It covers the core action and the most important behavioral nuance (auto-creation of parents). Some additional details about error handling or return values could improve completeness, but overall it is sufficient for a tool of this simplicity.

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

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

The schema already provides descriptions for both parameters (app and path) with 100% coverage, so there is a solid baseline. The description goes beyond the schema by explaining that parent directories are created automatically, which directly impacts how the 'path' parameter should be interpreted (e.g., nested paths are supported).

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

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

The description clearly states the action ('Create a directory') and the scope ('in an app'), using a specific verb and resource. It distinguishes from sibling tools like create_app or write_file by focusing on directory creation. The additional note about parent directories being created automatically adds further specificity about the tool's behavior.

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 context for when to use the tool: when you need to create a directory within an app. It implies that the tool handles nested paths automatically. However, it does not explicitly mention any alternatives or when not to use it, so it falls short of a full 5 but is still strongly contextual.

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 fully discloses the destructiveness: it permanently deletes the app, Docker service, volume, and all data including version history, and states 'This cannot be undone.' This goes well beyond structured data and alerts the agent to irreversible side effects, which is exactly what an agent needs for safe invocation.

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

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

The description is compact and front-loaded with the DESTRUCTIVE warning, followed by a precise list of what gets deleted and the irreversibility, then the mandatory confirmation instruction. Each sentence carries critical information with no wasted 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 the tool's irreversible destructive nature, no annotations, and no output schema, the description provides all essential context: what is affected, that it can't be undone, and that user confirmation is required. Sibling tools do not need explicit comparison because the deletion scope is unambiguous.

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 fully documents the single parameter 'app' as 'App ID (UUID) or subdomain' (100% schema coverage). The description adds no additional parameter-level detail, so it meets the baseline of 3 but does not exceed it.

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

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

The description uses the specific verb 'Permanently delete' with a clear resource ('an app') and enumerates the exact scope ('its Docker service, volume, and all data including version history'). This distinguishes delete_app from sibling tools like delete_file and stop_app, making the tool's purpose unmistakable.

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 clearly implies when to use this tool: when the user wants permanent, irreversible deletion of an app. The explicit 'You MUST confirm with the user before calling this tool' provides a critical usage prerequisite. However, it does not explicitly contrast with alternatives like stop_app or restart_app, so it stops short of full when-not guidance.

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

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

With no annotations, the description carries full burden. It clearly warns 'DESTRUCTIVE', discloses recursive deletion, lists protected paths, and mandates user confirmation for directory deletion. This is excellent behavioral disclosure beyond basics.

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 concise sentences, front-loaded with the 'DESTRUCTIVE' warning. Every word adds value: action, scope, recursion, restrictions, and confirmation requirement. No redundant information.

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

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

For a destructive tool with no output schema, the description covers all essential aspects: what is deleted, how (recursively), restrictions, and required confirmation. Context signals (2 params, no enums, simple schema) imply low complexity, and the description fully addresses the tool's 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 covers both parameters with 100% description coverage. The tool description adds no extra parameter-specific semantics beyond the constraints (cannot delete certain paths), which apply to the 'path' parameter but are not detailed per-parameter. Baseline 3 is appropriate since schema already documents each parameter.

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?

Clearly states the action 'Delete a file or directory in an app' with specific scope. Distinguishes from siblings like delete_app, remove_package, and rename_file by specifying file/directory deletion within an app.

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 clear context for when to use (deleting files/directories in an app) but does not explicitly name alternatives or say when not to use. The constraints (cannot delete package.json/node_modules, must confirm directories) give practical usage guidance.

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

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

No annotations are provided, so the description carries full responsibility for disclosing behavior. It only states 'Get detailed information' and 'including its Docker service status', which is minimal and does not reveal potential side effects, permissions, output format, or error conditions. The tool appears read-only but this is 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 immediately states the tool's purpose. It contains no redundant words or filler, making it efficient and easy to scan for an AI agent.

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

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

With no output schema, the description should explain what the returned detailed information includes. It only mentions 'Docker service status' but leaves the rest vague. It does not specify other potential fields, return structure, or when to prefer this over get_app_status, making it incomplete for a read tool without schema support.

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 describes the only parameter 'app' as 'App ID (UUID) or subdomain' with 100% coverage. The description adds no further semantic detail beyond 'specific app', which is consistent with the schema. Since schema coverage is complete, the baseline of 3 is appropriate.

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

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

The description clearly states the tool gets detailed information about a specific app, using the specific verb 'Get' and resource 'app'. It mentions 'including its Docker service status', which partially distinguishes it from get_app_metrics and list_apps, but does not explicitly differentiate it from the sibling tool get_app_status.

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 compared to alternatives like get_app_status or get_app_metrics. The description does not mention any exclusions, prerequisites, or specific scenarios, leaving the user without clear direction.

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

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

No annotations are provided, so the description carries the full burden. It discloses a prerequisite (the app must be running) and the resource types covered, but does not describe the return format, error behavior, or any read-only guarantees. This is a modest level of transparency for a simple read operation.

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 that conveys the exact purpose without any waste. Every word contributes meaning, fitting the standard of 'every sentence earns its place'.

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

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

For a simple one-parameter tool with no output schema and no annotations, the description is adequate but incomplete. It explains the 'what' but omits the 'when' and the shape of the response. Given the lack of annotations, more behavioral and usage context would be expected for full completeness.

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

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

Schema description coverage is 100% and clearly explains the 'app' parameter as 'App ID (UUID) or subdomain'. The description adds minimal context by referring to 'a running app container', but does not significantly enrich the parameter's semantics beyond the schema.

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

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

The description clearly states the verb 'Get' and the specific resource: CPU, memory, and network stats for a running app container. This distinguishes it from sibling tools like get_app or get_app_status, 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?

Usage is implied: the tool is for retrieving resource metrics for a running app. However, there is no explicit when/when-not guidance or mention of alternatives like get_logs or get_app_status, though the specificity of the stats makes the purpose self-explanatory.

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 states the output details and 'real-time' nature, but does not explicitly confirm that the operation is read-only or mention any error/edge-case behavior. It does not contradict anything; it's adequate but not rich.

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 that conveys the purpose and output in under 20 words. No filler or repetition.

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

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

For a simple status-checking tool with one parameter and no output schema, the description is nearly complete. It specifies what will be returned (replica count, running, health) but doesn't mention failure modes or the need for authentication, which would make it fully robust.

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

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

The input schema already describes the 'app' parameter as 'App ID (UUID) or subdomain,' giving 100% coverage. The description does not add additional detail about the parameter beyond referencing 'an app,' so it adds nothing beyond the schema.

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

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

The description uses a specific verb 'Get' and clearly defines the resource as 'Docker service status for an app.' It enumerates the exact data points (replica count, running state, health check status), which distinguishes it from sibling tools like get_app or get_app_metrics.

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 real-time status of an app's Docker service. However, it provides no explicit guidance on when to choose this over alternatives like get_app_metrics or get_app, nor does it mention 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, the description discloses the key behavioral traits: it returns the current status of an async operation and should be polled. It also explains the 'error' state includes an error message. This is sufficient for a read-only status checker, though it does not explicitly state it has no 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?

Two sentences deliver the purpose, return values, and usage timing without any redundancy or fluff. The description is well-structured and front-loaded.

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

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

The description covers purpose, return value semantics, and when to use the tool. For a simple, single-parameter status checker, this is nearly complete. It could optionally detail the error message format, but that is a minor gap.

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

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

The input schema fully documents the single 'app' parameter as an App ID or subdomain, covering 100% of parameters. The description adds no additional parameter detail, so the baseline score of 3 applies.

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

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

The description clearly states the tool checks npm install status and enumerates the four possible return values. It is specific to install operations, which distinguishes it from get_app_status, though it does not explicitly name alternatives.

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

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

The description explicitly instructs to poll after calling install_packages or remove_package, providing clear timing context. It does not mention exclusions or alternative tools, but the guidance is direct and 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?

No annotations are provided, so the description carries full burden. It discloses that the tool returns both stdout and stderr and implies a read-only operation via 'Get', but it does not mention side effects, authentication requirements, or default limits such as the tail=100 behavior. The schema partially compensates by describing filtering parameters.

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 and under 20 words, with the action verb 'Get' immediately conveying the purpose. It is front-loaded and contains no filler or redundant text.

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

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

The tool is simple and well-supported by the schema, which documents all parameters. The description gives adequate context for debugging use cases, and since no output schema is present, the return format is reasonably implied by 'console output'. The lack of annotations is a minor gap but not critical for this read-only 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?

All six parameters are fully described in the input schema (100% coverage), so the description does not need to add parameter-level details. The description adds no additional meaning about parameters, which is acceptable given the schema's completeness.

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 retrieves console output (stdout + stderr) for an app, with a specific verb and resource. It is distinct from sibling tools like get_app_status or get_app_metrics, and the mention of stdout/stderr precisely scopes the output.

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 context by stating it is useful for debugging runtime errors. However, it does not explicitly mention when not to use it or name alternative tools, though no sibling tool directly overlaps with log fetching.

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

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

No annotations are present, so the description must carry the full burden. It clearly conveys a read-only operation ('Read the content'), which is safe and non-mutating. However, it does not disclose details about return format, error behavior, or auth requirements, which would be valuable. The description is minimally adequate but not rich.

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

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

Two sentences, front-loaded with the primary action, followed by a concise usage hint. Every word earns its place; no fluff or repetition of schema details.

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

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

For a simple read operation with complete parameter descriptions and no output schema, the description adequately covers purpose and usage prerequisites. It names the tools to obtain inputs. It doesn't explain return value structure, but that is less critical given the description says 'content'. A minor gap is lack of edge-case behavior, but the scope is simple enough that the description is nearly complete.

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

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

Schema coverage is 100%, so parameters are individually documented. The description adds contextual meaning by telling users where to get the 'hash' (list_versions) and 'path' (get_version_files), linking parameters to other tools. This goes beyond the schema's basic descriptions, providing provenance for parameter values.

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 ('Read the content'), resource ('a specific file'), and temporal scope ('at a past version of an app'), clearly distinguishing from siblings like read_file (current version) and get_version_files (browse files). The purpose is unambiguous and well-differentiated.

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 explicitly names prerequisite tools: 'Use list_versions to get a commit hash and get_version_files to browse available files.' This tells the user exactly how to obtain the required parameters and implies when this tool is appropriate (when targeting a past version), providing clear usage guidance and alternatives.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only says 'list' without explicitly stating that the operation is read-only, nor does it mention return format, pagination, hidden files, or error conditions. This is a significant gap for a tool whose safety profile is not otherwise annotated.

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

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

Two short sentences with no filler. The action is front-loaded, and the prerequisite is stated in a second sentence. Every word earns its place.

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

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

There is no output schema, so the description should describe what the listing includes (e.g., names, types, recursion), but it does not. It also omits read-only status and any auth requirements. However, the schema is complete, and the tool's purpose is straightforward enough to make this minimally adequate, though with clear gaps.

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

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

The input schema covers all three parameters with clear descriptions (100% coverage), so the description does not need to repeat them. It adds a small hint (use list_versions) that also appears in the schema's hash description. The baseline of 3 is appropriate because the schema carries the parameter-semantics load.

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 lists files and directories at a specific commit, which is a specific verb+resource+scope. It also differentiates implicitly from siblings like list_files (current state) and get_version_file_content (content) by focusing on the listing at a version. The reference to list_versions for a valid hash clarifies the intended workflow.

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 explicitly instructs to use list_versions to get a valid commit hash, providing a clear prerequisite and indirectly indicating when this tool is appropriate. However, it does not explicitly contrast with alternatives like list_files or get_version_file_content, leaving some ambiguity for an agent deciding between tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool returns (clone URL and authentication instructions) and implies a read-only operation via 'Get', but it does not explicitly confirm no side effects, permission requirements, or error behavior. This is adequate for a simple getter but lacks explicit safety or prerequisite details.

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 concise sentences: the first front-loads the action (what it gets), and the second adds the usage context. No fluff or unnecessary details, making it efficient and well-structured.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers the essential purpose, usage, and expected output at a high level. It lacks details on response structure or prerequisites, but the low complexity makes these gaps less critical, and the description gives enough for an agent to select and invoke it 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?

The input schema already fully documents the 'app' parameter with a clear description ('App ID (UUID) or subdomain'), giving 100% schema coverage. The tool description adds no additional parameter context, so the baseline of 3 is appropriate per the rubric.

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 that the tool retrieves the Git clone URL and authentication instructions for an app, with a specific use case: helping users set up local development with Git push-to-deploy. This specific verb-resource combination distinguishes it from sibling tools that perform git actions like git_pull, git_push, set_git_remote, or remove_git_remote.

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 when to use this tool: 'Use this to help users set up local development with Git push-to-deploy.' However, it does not explicitly mention when not to use it or name alternatives, though the differentiation from git action tools is implicit through the 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 full burden of disclosing behavior. It states the action (pull) but does not mention potential side effects such as overwriting local changes, conflicts, or authentication requirements. As a mutation tool, this lack of detail is a significant gap.

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

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

The description is two sentences, concise, and front-loaded with the primary action. The prerequisite is stated in a separate sentence without unnecessary elaboration, making every word earn its place.

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

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

The tool is simple with a single parameter and no output schema, so the description does not need to explain return values. However, as a mutation tool without annotations, it is missing behavioral details about side effects or outcomes. The prerequisite is mentioned, but the description could be more complete by explaining what happens after the pull.

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

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

Schema description coverage is 100%, and the 'app' parameter is already fully described in the schema as 'App ID (UUID) or subdomain'. The description adds no additional parameter semantics beyond the schema, so the baseline 3 applies.

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

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

The description clearly states the action ('Pull the latest changes from the upstream Git remote into the app') with a specific verb and resource. It distinguishes itself from sibling tools like git_push (push), git_info (info), and set_git_remote (configure remote), 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 provides a clear prerequisite ('Requires a remote to be configured first via set_git_remote') which helps the agent understand when this tool can be used. It does not explicitly mention when not to use it or name alternative tools, but the context is clear enough for selecting this tool over related git operations.

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 convey safety and side effects. It correctly implies a mutating action and adds the prerequisite of a remote with PAT, but it does not disclose potential failure modes, whether the push could be non-fast-forward, or any other operational consequences. The behavior is straightforward, but the description could be more explicit about what happens on failure or conflict.

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

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

Two sentences, perfectly front-loaded with the action, then a useful prerequisite. Every word earns its place; no fluff or redundancy.

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

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

For a single-parameter mutation tool with no output schema, the description covers the purpose and a key requirement. It could mention that a remote must already be set (e.g., via set_git_remote) or what the return value looks like, but these are minor gaps given the simplicity of the operation.

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

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

The schema already fully documents the single parameter 'app' with its description. The tool description adds no extra semantic information beyond referencing 'the app's commits,' so it does not elevate beyond the baseline of having full schema coverage.

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

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

The description uses a specific verb ('Push') with a clear resource ('the app's commits to the upstream Git remote'), making the tool's function unambiguous. It distinguishes clearly from sibling tools like git_pull (pull) and set_git_remote (set), so no confusion.

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

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

It provides a clear precondition: 'Requires a remote with a Personal Access Token configured.' This tells the agent when the tool can be used, though it does not explicitly mention alternative tools or scenarios when not to use it. The context is sufficient for a simple push operation.

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

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

No annotations are provided, so the description carries the full burden. It discloses key side effects: 'Updates package.json and runs npm install inside the container.' It also implies async behavior by directing to get_install_status for polling. This goes beyond a simple 'installs packages' statement and gives meaningful context about the operation's nature.

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 exactly two sentences. The first sentence states the core action and resource; the second provides essential follow-up guidance. No filler or redundant information.

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

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

For a mutation tool with no output schema or annotations, the description covers the essential context: what is modified (package.json, container), the asynchronous nature, and the specific polling tool. It doesn't describe potential error cases or return values, but the information provided is sufficient to invoke and monitor the operation 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?

The input schema already describes both parameters comprehensively (app as 'App ID (UUID) or subdomain' and packages as an array with name/version/dev). The description adds no extra meaning about parameters, but since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Install one or more npm packages in an app.' It uses a specific verb (Install) and identifies the resource (npm packages in an app), which distinguishes it from sibling tools like remove_package, list_packages, and search_packages.

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 explicitly tells the agent to 'Use get_install_status to poll for completion,' which provides clear lifecycle guidance after invocation. However, it does not explicitly state when to avoid this tool or mention alternatives, though the verb itself implies when it 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?

No annotations are provided, so the description carries the full burden. It discloses the returned information (status, subdomain, resource limits) but does not explicitly state that this is a read-only operation or mention potential pagination or authentication. For a simple list action, the verb 'List' implies safety, and the description adds some behavioral context.

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

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

The description is a single concise sentence that is front-loaded with the main action and resource. Every word adds value, with no fluff or repetition.

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

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

For a simple list tool with no parameters and no output schema, this description is largely sufficient. It tells the user what is listed and which fields are returned. It could be slightly more explicit about whether it returns all apps or only those the user has access to, but overall it is complete enough.

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

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

There are zero parameters, so there is nothing for the description to explain beyond the schema, which is already complete (empty). The baseline of 4 is appropriate for a no-parameter tool.

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

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

The description clearly states the tool lists all Bonto apps with specific output fields (status, subdomain, resource limits). The verb 'List' plus resource 'all your Bonto apps' is specific and distinguishes it from siblings like get_app or get_app_status.

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 context for use is clear: when you need an overview of all apps. It does not explicitly exclude alternatives, but the purpose is distinct enough that no exclusions are necessary. No explicit alternatives are named, but the description implies a general listing use case.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the operation is a read-only listing and describes the return data (names, types, sizes), but does not specify details like recursion behavior or hidden files. This gives adequate transparency for a simple list operation.

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 short sentences that front-load the action and outcome. Every word is informative, with no filler or repetition of schema details.

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

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

The description covers the core functionality and return value shape, which is sufficient given the simple two-parameter schema and no output schema. It omits edge cases like recursion or permissions, but these are not essential for an agent to invoke the tool correctly. The schema provides the default path, and the return types are explained.

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

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

The input schema already provides descriptions for both parameters (app and path) with 100% coverage, so the baseline is 3. The description adds no additional parameter-level information beyond the schema, such as path format or examples.

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 names the resource ('directory in an app'), clearly distinguishing it from siblings like read_file and write_file. It also states the return contents (file names, types, sizes), 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 it (when you need directory contents), but it does not explicitly mention alternatives or exclusions. It lacks guidance such as 'use read_file for file content' or 'recursive listings are not supported'. Thus usage is implied but not explicitly differentiated.

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 for behavioral context. It clearly implies a read-only operation ('List'), which is useful but does not disclose potential failure modes, authentication requirements, or whether the response format might vary. It adds minimal value beyond the name and schema.

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

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

The description is a single, concise sentence that front-loads the main action ('List') and provides the key details (what is listed, where it comes from, and the additional Node.js version). Every word earns its place with 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?

Given the low complexity (one parameter, no output schema), the description adequately conveys what the tool returns (packages and Node.js version). It lacks explicit error conditions or edge cases, but for a simple listing tool this is sufficient. A slightly higher score would require more behavioral 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?

The input schema already fully describes the only parameter ('app') with a clear description ('App ID (UUID) or subdomain'). The tool description does not add further meaning or usage details for the parameter, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') with a clear resource ('npm packages') and source ('from package.json'), and distinguishes itself from siblings like install_packages, remove_package, and search_packages by focusing on read-only inspection. It also mentions the included Node.js version, adding further specificity.

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

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

The description implies this is for viewing installed dependencies and the Node.js version, but it does not explicitly state when to use this tool over alternatives. It does not mention any exclusions or provide a 'use this instead of...' pointer, so guidance is only implicit.

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

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

With no annotations, the description carries the full burden. It discloses the return content (hash, date, message) and the ordering (reverse chronological), which is behavioral information beyond the schema. It doesn't explicitly state side effects, but 'List' suggests a read-only operation.

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

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

Two sentences: the first states the primary purpose, the second adds return format and downstream usage. No redundant 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?

With no output schema, the description adequately describes the return value (commits with hash, date, message, reverse chronological order). It doesn't cover error cases or pagination, but for a simple list tool with documented parameters, it is largely 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 input schema already documents both 'app' and 'limit' with 100% coverage. The description adds no additional parameter semantics beyond referring to 'for an app', so it does not elevate 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 opens with a specific verb ('List'), names the resource ('commit history (version snapshots) for an app'), and clarifies the output fields and ordering, distinguishing it from sibling tools like restore_version or get_version_file_content.

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

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

It explains that hashes returned are used with other version tools to inspect or restore past states, implying this tool is for viewing history rather than acting on it. It doesn't name specific sibling tools as alternatives, but the guidance is clear.

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

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

No annotations are provided, so the description must cover behavioral traits. It mentions the output (6-digit code) and user action but does not disclose code expiration, rate limits, session requirements, or the need to poll check_login afterward. The tool's behavior beyond generating the code is 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 a single, concise sentence that front-loads the primary action. It is free of unnecessary detail and every word adds value.

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

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

With no parameters and no output schema, the description carries the burden of explaining the tool. It states that a 6-digit code is generated and that the user enters it, but it omits what happens after entry or how this relates to sibling tools like check_login, leaving the full authentication flow incomplete.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The description adds context about the code's purpose, which is helpful, and the baseline for 0 params is 4.

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: 'Generate a 6-digit device code for authentication.' This specifies a concrete action and output, distinguishing it from sibling tools like check_login (which checks login status) and set_token (which sets a token).

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 says 'The user must enter this code on the Bonto website while logged in with their SideQuest account,' which implies it is part of an authentication flow. However, it does not explicitly state when to use this tool versus alternatives or mention when not to use it. There is context but no direct guidelines.

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 thoroughly discloses behavioral traits: maximum file size (1MB), binary file unsupported, default full-file read, optional line offset/limit behavior, and output format (cat -n with line numbers starting at 1). This fully compensates for the absence of structured annotations.

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

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

The description is concise and well-structured, starting with the core purpose, then stating key limitations, default behavior, parameter guidance, and output format. Every sentence provides distinct, useful information without redundancy.

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

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

The description is complete for a file-reading tool with no output schema: it covers parameters, defaults, constraints, and return format. It also gives enough context to handle large files appropriately. No critical behavior is left unexplained.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds meaningful context by explaining the default complete-file read, the purpose of offset/limit for large files, and the recommendation to omit them. It also clarifies the output numbering format, going beyond the schema.

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

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

The description clearly identifies the tool as reading file contents within an app, using the specific verb 'Read' with a clear resource ('file in an app'). It distinguishes itself from sibling tools like write_file, upload_file, list_files, and search_files by focusing on reading existing file contents.

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 context: it explains the default behavior of reading the entire file and recommends not providing offset/limit parameters except for large files. However, it does not explicitly compare against alternatives like get_version_file_content or state when not to use this 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action without mentioning prerequisites, side effects, irreversibility, or error conditions, leaving the agent without safety-related context for this mutation.

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

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

The description is a single, concise sentence with the verb front-loaded. Every word is necessary, and no extraneous information is present.

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 mutation tool, the description states the core action but lacks behavioral context such as consequences of removal or any requirement for the app to exist. Given no annotations or output schema, this is minimally adequate but incomplete for an agent to understand the full impact.

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

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

The schema already fully describes the only parameter 'app' as an App ID or subdomain (100% coverage). The description adds no further parameter semantics, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Remove' and clearly names the resource 'upstream Git remote' within the context of an app. This distinguishes it from sibling tools like set_git_remote (which sets a remote) and git_info (which shows information).

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 provided for when to use this tool versus alternatives. The usage is implied by the action name and description, but there are no stated exclusions or references to sibling tools that would help an agent decide.

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 explaining side effects. It does disclose that it 'Updates package.json and runs npm install to clean up node_modules,' which is important behavioral context. It also implies asynchronous behavior by instructing to poll for completion. However, it doesn't mention reversibility, error cases, or permission requirements, leaving some transparency gaps.

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 main action, and every sentence provides meaningful information. It is efficient with no redundant text 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 that there is no output schema and no annotations, the description explains the tool's behavior well: it updates package.json, runs npm install, and directs the user to poll for completion. This covers the essential operational context for a mutation tool. It could mention prerequisites or edge cases, but for a 2-parameter tool, it is fairly 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 input schema already provides full descriptions for both parameters (app and name), so schema coverage is 100%. The description does not add any additional parameter-level meaning beyond what the schema already states. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Remove an npm package from an app.' This is a specific verb+resource combination that distinguishes it from siblings like install_packages, list_packages, and search_packages. The additional details about updating package.json and running npm install reinforce its purpose.

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

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

The description gives clear context for when this tool is used (to remove packages) and explicitly instructs to 'Use get_install_status to poll for completion,' which is a useful operational guideline. However, it doesn't explicitly state when not to use it or compare with alternatives like install_packages, so it stops short of a fully explicit when/when-not guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only mentions the protected-paths restriction but does not disclose that rename/move is a destructive operation (removes old path), potential permission requirements, or behavior on conflicts (e.g., overwriting). This is insufficient for a mutation tool.

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

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

The description is front-loaded with the core purpose in the first sentence and a key limitation in the second. It is minimal, with no wasted words, and every sentence earns its place.

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

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

The tool is a mutation with 3 well-documented parameters. The description covers the main function and a notable constraint, but it omits potential side effects (e.g., moving deletes the original) and prerequisites (e.g., app permissions). Thus, it is adequate but with clear gaps for a mutation tool.

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

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

Schema description coverage is 100%, with each parameter having a clear description (app, old_path, new_path). The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description uses specific verbs ('Rename or move') and identifies the resource ('a file or directory in an app'). This clearly distinguishes it from sibling tools like delete_file or write_file. The mention of protected paths adds a precise scope.

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

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

The description gives clear context for when to use the tool (renaming/moving files/directories) and includes a specific exclusion (protected paths). However, it does not explicitly name alternatives or provide when-not-to-use guidance beyond the protected paths.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that soft restart preserves terminal sessions and restarts only the app process, while hard restart kills terminal sessions and restarts the container. This goes beyond a mere 'restart' and clarifies side effects, though it does not mention auth requirements or potential failures.

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, front-loaded with the core purpose, and every word earns its place. It avoids redundancy and clearly structures the default vs. hard-restart cases.

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 2-parameter tool with no output schema, the description covers the essential context: what happens by default, when to use hard restart, and the key side effect (terminal session preservation/kill). It lacks return value or error info, but given the action-oriented nature and lack of output schema, this is adequate.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds value by providing the example 'after env var changes' for hard=true, and by explaining the behavioral difference between soft and hard restarts beyond what the schema states. This enriches parameter understanding beyond the structured 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 begins with a specific verb and resource: 'Restart a running app.' This clearly distinguishes it from sibling tools like start_app, stop_app, and get_app_status. It also adds meaningful nuance by explaining soft vs. hard restart modes.

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 explicit usage guidance for the hard parameter ('Set hard=true for a full container restart when needed (e.g. after env var changes)') and explains the default soft restart behavior. However, it does not explicitly mention alternatives (e.g., when to use start_app vs. restart_app) or when not to use the 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?

With no annotations, the description fully discloses the destructive nature: 'permanently overwrites all current files', 'changes made after that commit will be lost and CANNOT be recovered'. It also mandates user confirmation, which is critical for a destructive tool.

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

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

Three sentences, front-loaded with 'DESTRUCTIVE' warning, every sentence earns its place. No redundant 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?

Given the tool's destructive nature and lack of annotations/output schema, the description covers side effects, irreversibility, user confirmation, and prerequisite action (list_versions). It is fully complete for safe invocation.

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

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

Schema description coverage is 100%, with app and hash already well described. The description adds no additional parameter details, but does not need to since the schema fully documents them. Baseline 3 is appropriate.

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

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

Clearly states 'Restore an app to a previous version using git reset --hard', specifying the verb (restore), resource (app), and method (git reset --hard). This differentiates it from sibling tools like git_pull (which updates to latest) and list_versions (which only lists versions).

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

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

Explicitly instructs when to use the tool and provides prerequisites: 'Use list_versions to show the user available versions first' and 'You MUST confirm with the user before calling this tool'. This gives clear usage context and user-interaction requirements.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that node_modules, .git, and binary files are skipped, that results are capped at 500 by default, and that output can be grouped by content, files, or counts. This goes well beyond the schema by revealing real execution behavior and 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 tightly written, with the first sentence stating the core purpose and the second adding return behavior. The second paragraph efficiently summarizes advanced options without redundancy. Every sentence contributes meaningful detail, and the structure front-loads the most important 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?

Despite having 10 parameters and no output schema, the description covers the essential behaviors: search scope, return format, exclusions, result limit, and supported grep-like options. The schema covers individual parameter specifics, so the description provides sufficient high-level context for correct tool selection and 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 input schema already covers all parameters with descriptions, so the baseline is 3. The description adds value by giving concrete examples for glob patterns ('*.ts', 'src/**/*.ts'), explaining context flags (-A/-B/-C), and naming output modes. It enhances understanding beyond the raw schema definitions.

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

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

The description opens with a specific action ('Search for text across all files in an app') that clearly identifies the tool's purpose and resource. It distinguishes itself from siblings like read_file and list_files by focusing on content search with line numbers. The scope ('in an app') and the return grouping are explicitly stated.

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

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

The description gives clear context for when to use the tool: when you need to search across all files rather than reading a specific file. It does not explicitly name alternatives or state when-not-to-use, but the 'grep-like' framing and options imply its role. The exclusion of node_modules, .git, and binary files also helps set expectations.

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

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

No annotations are present, so the description carries the full burden. It discloses the result limit ('up to 10 results') and the returned fields (name, description, latest version), which are meaningful behavioral details. The verb 'search' implies a read-only operation, providing some transparency about side effects, though it does not explicitly state safety or network dependencies.

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 concise sentences, front-loaded with the core action. No redundant information or fluff, making it highly efficient.

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

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

For a simple tool with one parameter and no output schema, the description is reasonably complete: it explains what it does, the result limit, and the return format. The only notable omission is guidance on when to use it versus sibling tools, but that is more relevant to usage guidelines than completeness.

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

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

Schema description coverage is 100%, with the 'query' parameter described as 'Package name or keywords to search for'. The tool description adds no additional meaning beyond this, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Search the npm registry for packages.' This uses a specific verb ('search') and resource ('npm registry'), distinguishing it from siblings like list_packages (which likely lists local packages). The mention of return fields further clarifies its purpose.

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

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

No usage guidance is provided. The description does not state when to use this tool versus alternatives such as list_packages or install_packages, nor does it mention any prerequisites or exclusions. Users are left to infer appropriate usage from the tool name.

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

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

With no annotations, the description carries the burden. It discloses that the tool sets or updates the remote and explains token requirements for private repos. However, it does not mention whether the operation overwrites an existing remote, prerequisites like an initialized Git repo, or potential side effects, leaving some ambiguity for a mutation tool.

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

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

The description is two sentences, front-loaded with the action, and every word earns its place. It efficiently conveys the core functionality and the main variation (token for private repos) without repetition.

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

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

For a straightforward remote-configuration tool, the description covers the essential purpose and key nuance (token for private repos). The schema covers all parameters and no output schema exists, so the description is reasonably complete. However, it could include a brief note about overwriting behavior or when to use git_info instead, but these are minor gaps.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description adds marginal clarification about token use (public vs. private) but does not provide significant new meaning beyond the schema fields.

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 'Set or update the upstream Git remote (GitHub/GitLab) for an app', using a specific verb and resource. It distinguishes from siblings like remove_git_remote and git_pull by indicating this is specifically for configuring the remote source.

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 clear context on when to use the tool (setting/updating remote) and notes public vs. private repo token requirements. However, it does not explicitly state when not to use it or name alternative tools for similar operations.

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 key side effects: 'Updates package.json engines.node and restarts the container with the new Node.js image.' This provides useful behavioral context about the mutation and restart, though it does not mention permissions, reversibility, or potential downtime duration.

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 front-loads the main action and then lists the side effects. It is concise with no filler words, every part earning its place.

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

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

For a tool with only two parameters and clear schema coverage, the description is largely complete. It explains the core action and side effects. However, it does not mention preconditions (e.g., app must exist) or return behavior, but given the tool's simplicity, this is a minor gap.

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

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

The input schema already describes both parameters (app and version) with clear descriptions and an enum for version. The description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Change the Node.js runtime version for an app'. It also explicitly lists the allowed versions (18, 20, or 22), making it distinct from general app update or restart tools.

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

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

The description implies usage when you need to change the Node.js runtime version, but it does not explicitly state when to use this tool over alternatives like update_app or restart_app, nor does it mention exclusions or prerequisites. The context is clear but not fully elaborated.

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 token source, the timing of use, and the fallback behavior on invalid token. It does not describe response details or side effects, but for this simple tool it provides meaningful behavioral context.

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

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

Two sentences, front-loaded with the main purpose. The second sentence packs usage timing and fallback without fluff. Every phrase earns its place.

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

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

For a one-parameter tool with no output schema, the description covers purpose, exact usage timing, token source, and failure fallback. This is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% (token parameter is documented). The description adds 'previously saved JWT token' but this largely mirrors the schema's 'saved from a previous bonto_check_login response'. No significant additional parameter semantics beyond the schema.

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

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

Clearly states it restores an authenticated session using a previously saved JWT token. Distinguishes from siblings by specifying token source (check_login) and fallback (login).

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

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

Explicitly instructs to call at the start of a new session before any other tools, and provides a fallback to login if the token is invalid. This directly addresses when to use vs alternatives.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds a concrete detail by explaining the action as 'scaling its Docker service to 1 replica', which goes beyond the bare name. It does not mention side effects, permissions, or error behaviors, but for a simple start operation this is adequate.

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

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

The description is one sentence, front-loaded with the action, and contains no redundant information. Every word is purposeful.

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

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

This is a simple tool with one parameter and no output schema. The description covers the purpose and the mechanism, and the schema documents the parameter. It does not specify behavior for edge cases (e.g., already running apps), but given the low complexity, the description is sufficiently complete.

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

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

The input schema fully describes the single 'app' parameter as 'App ID (UUID) or subdomain' (100% coverage). The description adds no additional parameter meaning, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: to start a stopped or sleeping app by scaling its Docker service to 1 replica. The verb 'start' and resource 'app' are specific, and the mechanism differentiates it from sibling tools like stop_app and restart_app.

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

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

The phrase 'stopped or sleeping app' implies the tool should be used for apps that are not currently running, giving context for when to use it. However, it does not explicitly name alternatives or state exclusions (e.g., what to do if the app is already running).

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 covers the key behavioral consequence: the app becomes inaccessible to visitors. By noting 'until started again,' it implies reversibility. It does not cover additional side effects like data persistence or prerequisites, but it adequately discloses the primary effect for a stop operation.

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 that states purpose, mechanism, and consequence without any filler. Every phrase adds meaningful information, making it highly concise and well-structured.

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 tool's simplicity (one parameter, no output schema, no annotations), the description covers the essential context: what action is performed, how it is performed, and the user-visible effect. It does not describe return values or edge cases (e.g., already stopped), but these are less critical for a stop operation.

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

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

The single parameter 'app' is fully documented in the schema with the description 'App ID (UUID) or subdomain,' providing 100% coverage. The tool description does not add additional parameter-level detail beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly identifies the action (stop), the resource (running app), and the mechanism (scaling Docker service to 0 replicas). It distinguishes this from sibling tools like start_app or restart_app, making the purpose explicit and unambiguous.

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

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

The description implies when to use the tool: to make an app temporarily inaccessible while preserving the ability to start it again. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of fully explicit usage guidance.

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

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

With no annotations, the description must convey behavioral traits, but it only lists settings categories. It omits important side effects such as env_vars replacing all existing variables, subdomain changes recreating the Docker service, or that some changes are capped by billing tier. This is a significant transparency gap for a mutation tool.

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

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

The description is a single concise sentence that front-loads the main action and lists key categories. Every word is functional, and it avoids unnecessary detail.

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

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

For a complex tool with 22 parameters, no output schema, and no annotation support, the description is far too brief. It does not mention that updates are partial (only provided fields change), whether changes trigger restarts, or what the response contains. The schema covers parameter details, but the description fails to provide the high-level context needed for a tool of this complexity.

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 100% coverage of all 22 parameters with detailed descriptions, so the baseline is 3. The description adds minimal extra meaning by grouping parameters into categories like 'resource limits' and 'access control', but does not provide any new parameter-level semantics beyond the schema.

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

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

The description clearly states the tool's function as updating an app's settings, with a specific verb (update) and resource (app's settings). It lists the categories of settings (name, subdomain, environment variables, resource limits, access control, runtime configuration), which differentiates it from sibling tools like create_app, delete_app, or get_app.

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 that this tool is for modifying existing apps but does not provide explicit guidance on when to use it vs alternatives. It does not mention that this should be used only for existing apps, nor does it explain when to use restart_app or other tools.

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

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

With no annotations, the description carries the full burden and discloses key behavioral traits: the URL is one-time, valid for 5 minutes, and uploads must be raw binary rather than base64. It also notes compatibility with any file type. Missing details like authentication requirements or size limits, but the disclosed constraints are highly valuable for safe execution.

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, front-loaded with the main action, and every sentence adds necessary information (purpose, validation, workflow, compatibility). There is no wasted wording or repetition.

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

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

For a simple 2-parameter tool with no output schema, the description is largely complete. It covers the core workflow (get URL, POST via curl), key constraints (5-minute expiry, raw binary), and file-type flexibility. It could mention prerequisites like app existence or size limits, but the current level is adequate for an AI agent to proceed.

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 100% description coverage for both parameters, so the baseline is 3. The description does not add additional parameter-level details beyond what the schema already provides (e.g., app ID/subdomain and destination path examples).

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 explicitly states the tool 'Get a direct upload URL for uploading a binary or text file to an app', which is a specific verb+resource combination. It also clarifies scope by mentioning 'any file type' and 'raw binary', effectively distinguishing it from siblings like write_file or rename_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 gives clear context on when to use this tool (for direct uploads of binary/text files) and how to use the returned URL ('use the Bash tool to POST the file with curl'). It lacks an explicit comparison to alternatives, but the workflow guidance is strong enough to guide correct selection.

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

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

With no annotations present, the description carries the full burden of disclosing behavior. It covers three important side effects: automatic creation of parent directories, the 1MB content cap, and automatic app restart on file changes. It does not mention overwrite semantics or permission requirements, but the main effects are well documented.

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

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

The description is four concise sentences, each providing essential information. It is front-loaded with the core action and contains no redundant or filler 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 3-parameter write tool, the description covers the main action, path behavior, size limit, and restart side effect. It does not describe return values or error cases, but that is not critical given the straightforward nature of the operation and the absence of an output schema.

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

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

All three parameters are already described in the schema, so the baseline is 3. The description adds value by linking the path parameter to automatic parent directory creation and the content parameter to the 1MB limit, which goes beyond simple schema definitions.

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 'Create or update a file in an app' with a specific verb and resource. It distinguishes itself from sibling tools like read_file, delete_file, and rename_file by focusing on writing file content.

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

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

The description implies usage for writing or updating file contents, and adds practical constraints like automatic directory creation and the 1MB size limit. However, it does not explicitly mention when to use this tool over upload_file or when not to use it.

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