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

With no annotations, the description carries full burden and delivers richly: discloses appending behavior, alias mapping, async execution, top-level await support, timeout counting, and the critical requirement that assertions must be wrapped in test() to be recorded. This goes far beyond generic 'adds a script'.

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 yet information-dense, with the primary purpose front-loaded. Every sentence adds value—aliases, modes, async details, timeout. 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?

Despite no output schema, the description covers behavior, modes, aliases, runtime environment, timeout, and alternatives. It fully equips an agent to select and invoke the tool correctly for typical use cases.

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%, but the description adds significant meaning beyond schema descriptions: explains script body expectations (test() wrappers, res.getBody() behavior), append/replace semantics, and scriptType aliases. It compensates and enhances parameter understanding.

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+resource: 'Add pre-request, post-response, or tests scripts to a Bruno request.' It clearly names the tool's action and object, and the mention of scriptType values distinguishes it from sibling tools like remove_script or modify_request.

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 covers when to use append vs. replace, and points to remove_script as the alternative for clearing scripts. It also directs users to modify_request's settings argument for timeout adjustments, showing awareness of 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 full burden. It discloses key side effects: the collection is added to the workspace registry, and list_collections reads that registry rather than the disk. It also explains the result indicates registration status and failure reasons. This is unusually transparent for a creation 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 concise yet packed with necessary information. Every sentence earns its place: definition, path behavior, registry warning, and result explanation. It is well-structured and easy to parse.

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 side effects and a registry integration, the description covers all essential aspects: creation location, naming, registration behavior, and result content. It also explains the default workspace path. Without an output schema, the description still gives a sufficient picture of what to expect.

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 only 38%, so the description must compensate. It does so by explaining outputPath's parent-directory semantics with a concrete example and clarifying how registerInWorkspace and workspacePath interact with the registry. Other parameters like format, ignore, baseUrl, and description remain simple, but the critical, error-prone ones are well covered.

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 it creates a new Bruno API testing collection, with a specific verb and resource. It distinguishes itself from sibling tools like delete_collection and list_collections by focusing on the creation side-effect and registry integration.

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 usage, including the exact path semantics and the registry behavior that affects visibility. It does not explicitly mention alternatives like create_crud_requests, but it provides enough guidance on how to operate correctly, including a 'do not' warning about duplicating the collection 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?

No annotations exist, so the description carries the full burden. It discloses an important behavior: 'All five inherit the collection or folder auth block unless you pass auth.' However, it omits other behavioral details such as file system effects, overwrite behavior, or error conditions, 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 concise sentences, front-loaded with the primary action and a key behavioral note. Every word earns its place with no filler or redundancy.

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

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

The tool is moderately complex (5 parameters, nested auth object, no output schema), and the description is too sparse to be complete. It does not explain how entityName is used, what baseUrl does, where the requests are written, or what the tool returns. For a batch generation tool, this is a significant gap.

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

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

Schema description coverage is only 40%, with descriptions for auth and collectionPath. The tool-level description adds minimal parameter clarification; it mentions 'auth' but does not explain entityName, baseUrl, or folder. With low schema coverage, the description should compensate, but it does not.

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 complete set of CRUD operations for an entity: list, get by id, create, update, delete.' It names the specific resource (an entity) and distinguishes itself from sibling tools like create_request (single request) by producing five operations at once.

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 the primary use case: scaffolding full CRUD for an entity. It is clear when to use this tool, but it does not explicitly mention alternatives or exclusions (e.g., 'use create_request for a single request'). This qualifies as clear context without explicit 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 provided, the description carries the full burden and does so thoroughly. It discloses that the tool writes the whole file, refuses existing names rather than overwriting, reports which existing variables would be deleted, and explains the remedy. This gives the agent a strong sense of the mutation risk and failure modes.

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, focused sentence that front-loads the primary purpose, then packs the critical caveat and resolution options into a well-structured clause. There is no filler or repetition; 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?

Given the lack of annotations and output schema, the description covers the essential behavioral context: creation, overwrite refusal, error details, and interaction with update_environment. Combined with the rich parameter schemas, the agent has everything needed to invoke the tool safely and choose the right alternative.

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 75%, so the schema already explains most parameters in detail, including the two forms of variables and the overwrite flag. The description adds practical meaning by tying overwrite to the retry path after a refusal, and by mentioning 'which ones a replace would delete,' which helps the agent interpret the consequences of setting overwrite.

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

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

The description opens with a specific verb and resource: 'Create an environment file for a Bruno collection.' It also distinguishes the tool from sibling update_environment by highlighting that existing names are refused rather than overwritten, clarifying its unique 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?

Explicitly provides guidance for the main conflict scenario: when a name already exists, the agent is directed to choose between merging via update_environment, picking another name, or retrying with overwrite: true. This names a concrete alternative and gives clear when-not-to-use context, going beyond a generic 'use for creation.'

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 transparency burden and does so well: it discloses that scripts run as async functions, that top-level await and bru.sleep/setTimeout/setInterval work, that the script timeout defaults to 5000ms and can be raised via settings, and that websocket/grpc requests reject HTTP method/body semantics. It does not mention overwrite behavior or error cases, but the disclosed behavioral traits go well beyond a minimal statement.

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 dense and information-rich, front-loaded with the core purpose and format support, then branching into kind-specific and script-specific details. It earns its length for an 18-parameter tool, though a single long paragraph could be better structured with bullets or section breaks for skimmability.

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 high complexity (18 params, nested objects, no output schema), the description covers the essential orientation: file formats, three transport kinds, key body modes, script execution semantics, and timeout handling. It does not explain return values or overwrite behavior, but the combination of description and rich input schema gives an agent sufficient context 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 50%, so the description should add semantic meaning, and it does: it explains how kind interacts with method/body, what form-data file uploads require, and how settings.timeout relates to script execution. The schema itself carries rich descriptions for many properties, and the main description ties key parameters together without simply repeating 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 opens with a specific verb and resource: 'Generate request files for API testing' and immediately names the supported formats (.bru and .yml). It distinguishes itself from siblings by stating that inline scripts mean 'no separate add_test_script call is needed' and by clarifying the kind-specific behavior (http, websocket, grpc), 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 gives clear context on when to use create_request: to author request files, with explicit guidance on kind selection and the script inclusion alternative. It does not provide exhaustive when-not guidance against all siblings (e.g., create_crud_requests or modify_request), but the inline-script note and kind distinctions offer solid usage context.

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

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

With no annotations provided, the description carries full responsibility for behavioral transparency. It fails to disclose what 'generate' means in terms of side effects (e.g., file creation), whether it overwrites existing suites, or any dependencies like collectionPath needing to exist. Only weak inference from param names suggests creation behavior.

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

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

The description is a single, concise sentence that front-loads the core purpose. It is efficient with words, though it lacks critical detail, which is more a completeness issue than conciseness.

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 complexity of the schema (arrays of requests with auth, body, folders, dependencies), the description is woefully incomplete. It doesn't mention how requests are structured, how dependencies (from/to) work, or the requirement for an existing collectionPath. A richer description is needed to guide the agent.

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

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

With only 25% schema coverage (only collectionPath has a description), the description must clarify parameter usage. It only mentions 'related requests' without explaining how requests, suiteName, dependencies, or collectionPath function. The description adds minimal value 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 'Generate comprehensive test collections with multiple related requests' clearly states the verb ('Generate') and resource ('test collections'), and hints at the multi-request nature. However, it doesn't distinguish itself from sibling tools like create_collection or create_crud_requests, making it less effective at differentiating.

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

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

The description provides no guidance on when to use this tool versus alternatives like create_collection or run_collection. It lacks any mention of context, prerequisites, or exclusions, leaving the agent without direction on tool 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, the description fully discloses the destructive nature: permanent, irreversible, deletes entire directory and registry entry, and restricts to collection roots. It also mentions no recovery through the server. This covers all critical behavioral traits.

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 concise sentences: first states the core action and scope, second adds irreversibility, third provides a safety condition and an alternative. No redundant words, 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?

For a destructive tool with no output schema and no annotations, this description is fully complete: it explains the exact effect, the validation constraint, and the alternative tool. Sibling context is addressed by naming unregister_collection. Nothing essential is missing.

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

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

Schema descriptions cover 100% of parameters, so the description does not need to repeat them. It adds no new parameter-specific semantics beyond what the schema already provides (e.g., the confirm flag requirement and path guidance are already in the schema). 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?

The description clearly states the tool permanently deletes a Bruno collection including its directory and registry entry, and distinguishes it from unregister_collection which only stops listing. The verb 'delete' plus resource 'collection' and specific scope (directory + registry) makes 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?

Explicitly states when to use (permanent deletion) and when not to (if you want to keep files, use unregister_collection). Also provides a safety condition: only collection roots are valid, preventing misuse. This is exemplary 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 behavioral disclosure. It explicitly states the action is permanent ('cannot be recovered through this server') and describes the mechanism ('the file is unlinked from disk'). It also discloses the file type and collection scope limitation, providing essential transparency for a destructive 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 concise and well-structured: the first sentence states the action, the second adds context and consequence, and the third clarifies constraints and an alternative. Every sentence adds value, with 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?

Given the tool's destructive nature, the description covers all essential context: permanence, scope, file type restrictions, and a clear alternative. The schema fully documents parameters, and no output schema is needed for a simple delete operation. The description is sufficiently complete for an agent to select and invoke the tool safely.

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

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

Schema coverage is 100% for both parameters, and the schema descriptions are already detailed (e.g., filePath explains it is an absolute path and suggests sources like list_requests). The tool 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 purpose: 'Permanently delete a Bruno request file from a collection.' It uses a specific verb (delete), identifies the resource (request file), and explicitly distinguishes from sibling remove_script by saying 'To clear just a script and keep the request, use remove_script instead.'

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: 'Use this to remove a request created by mistake' and names the alternative tool for a related but different task. It also states constraints (only .yml/.bru files inside a detected Bruno collection), giving the agent explicit guidance on when this tool is appropriate.

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

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

The description explains the behavior thoroughly: it returns counts and details, mentions that environment variable values are withheld, and discusses response size and filtering side effects. Although no read-only annotation exists, the nature of 'Get statistics' implies no modifications, and the description makes the operational behavior clear.

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 well-structured in two logical paragraphs: first describing the output components, then addressing response size and filtering. It is concise, with no redundant phrasing, and every sentence adds valuable 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 complexity—multiple filtering options, response size considerations, and the relationship between counts and per-request data—the description covers all necessary aspects, including the use of filePath in run_collection, making it self-sufficient for an agent.

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 five parameters (collectionPath, folder, method, nameContains, includeRequests) are mentioned and explained in the description. It details the semantics of each, such as folder nesting, case-insensitivity, and the meaning of includeRequests, exceeding the bare schema documentation.

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: 'Get statistics about a Bruno collection' with specifics on counts by method, folders, environments, and per-request details. It distinguishes itself by providing filePath for use in run_collection, making its unique purpose evident.

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?

Explicit guidance on when to use the tool is provided: to obtain statistics and to use filePath values in run_collection. It also explains how to narrow results via folder, method, nameContains, and includeRequests, and clarifies the distinction between total counts and matchedRequests.

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 key behavioral traits: it is a registry listing, not a filesystem scan; unregistered disk collections won't appear; and non-existent registered entries return 'exists': false. This goes beyond the schema and provides crucial context for correct interpretation.

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 three sentences, each serving a distinct purpose: stating the core function, explaining the registry behavior, and giving usage guidance. It is concise, front-loaded, and free of 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?

Despite having no output schema, the description explains the key outputs (names, paths, exists) and how to use them with other tools. Given the simple nature of the tool (one optional parameter) and the rich behavioral detail provided, the description is complete enough for an agent to use 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?

The input schema has one parameter (workspacePath) with complete description coverage (100%), so the description does not need to add parameter details. The description does not mention workspacePath, but the schema already documents it adequately, 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 clearly states the tool lists Bruno collections registered in workspace.yml with their names and paths. It distinguishes itself from a filesystem scan and explicitly contrasts with other tools that use the path, making its purpose unambiguous.

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

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

Provides explicit guidance: if you already know the absolute path, pass it directly to other tools instead of using this. It also instructs to use the returned path as collectionPath in get_collection_stats, list_requests, and run_collection, clarifying when this tool is appropriate.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful context: the tool returns absolute file paths and specifies the file formats (.yml/.bru). However, it does not state whether the tool is read-only (though 'List' implies it), nor does it disclose error behavior or recursion depth. It is adequate but not rich in transparency.

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, consisting of two sentences that are front-loaded with the core purpose. Every sentence adds value: the first states what the tool does, the second explains the output format and its integration with run_collection. 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 low complexity (one parameter, no output schema), the description is quite complete. It explains the return value (absolute file paths) and their usability in run_collection. A minor gap is that it does not clarify whether subdirectories are traversed, but this is not a critical omission for a listing tool.

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

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

The input schema already provides a clear description for collectionPath: 'Absolute path to collection directory. Use the path returned by list_collections.' Since schema coverage is 100% and the description adds no additional parameter-level guidance, 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 states a specific action: 'List all request files (.yml/.bru) in a Bruno collection.' It clearly identifies the resource (request files) and scope (collection), and distinguishes from sibling tools like list_collections (which lists collections) and read_request (which likely reads a request's 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 provides clear context on how to use the output: 'absolute file paths, each usable as an entry in the requests list of run_collection, or of one of its groups.' This effectively tells the agent when to use this tool (to get request paths for running a collection) and how the returned values integrate with run_collection. 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 disclosure burden, and it delivers: partial-merge preservation of unprovided fields, idempotent script replacement (repeated calls do not accumulate), the append escape hatch, and the subtle name/filename independence mirroring Bruno's own behavior. It also points the caller to read the new path from the response after a rename. It doesn't cover reversibility or auth requirements, but for a file-editing tool the disclosed traits go well beyond the minimal mutation hint.

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

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

The description is three dense sentences, front-loaded with the core merge semantics before moving to script behavior and rename rules. Every sentence carries non-redundant information; the append-mode, remove_script reference, and filename/name distinction each earn their place. Slightly long for a one-liner, but the density justifies the length given the tool's complexity.

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 high complexity (17 parameters, nested objects for auth/body/grpc/settings/websocket/vars) and no output schema, the description covers the cross-cutting behaviors — merge semantics, script modes, file uploads, rename handling — while the schema exhaustively documents individual fields. It even hints at the response contract ('read the new path back from the response'). The only gap is that it delegates most parameter behavior to the schema, which is acceptable since the schema is thorough.

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 59%, so the description partially compensates. It adds value by explaining the global partial-merge semantics that apply to every provided field, clarifying scriptMode's append/replace distinction, and unpacking the name-vs-filename independence beyond what the schema's bare descriptions state. The heavy per-parameter detail (auth, grpc, settings, websocket) is already richly documented in the schema itself, so the description need not repeat 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 opens with a specific verb+resource: 'Update an existing Bruno request file with partial-merge semantics.' This clearly distinguishes it from siblings: create_request (new files), read_request, delete_request, and move_request are all named different actions. The partial-merge framing immediately separates it from create_request's full-write 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 gives clear usage context: it targets existing files ('Update an existing...') versus create_request, and explicitly names an alternative tool — 'Use remove_script to clear a script entirely' — when clearing is needed rather than replacing. It also explains when to choose append vs. replace via scriptMode. It doesn't enumerate exclusions against every sibling, but covers the key decision points for a modify 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 carries the full burden of behavioral disclosure. It goes above and beyond by explaining that the move is byte-verbatim, that seq may tie and are resolved by filename, and that the new path is returned. This level of detail is outstanding and far exceeds the minimum.

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: three sentences that carry substantial information without fluff. It leads with the primary purpose, then covers the key nuance (copy mode), and concludes with behavior and an alternative. Every sentence adds value, and the structure is 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?

Given the tool's complexity, the description is remarkably complete. It explains the return value (new path), an edge case (seq ties and resolution), and the difference between move and copy. There is no output schema, so the description appropriately covers the response. It also provides guidance on selecting destinations via parameters.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description reinforces the copy semantics and notes that the file keeps its name, but these are more behavioral than parameter-specific. It does not add significant new meaning beyond the schema, but it does not need to.

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

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

The description clearly states the tool's purpose: 'Relocate a request file to another folder, or to another collection entirely.' It specifies the verb (relocate), the resource (request file), and the two primary operation modes (move and copy). It also distinguishes from sibling tools like modify_request by noting that renaming is handled there.

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

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

The description provides explicit guidance on when to use copy:true versus moving, and explicitly points to modify_request for renaming, which differentiates it from that sibling. It does not explicitly list all alternatives or exclusion criteria, but the context is clear enough for typical usage.

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 takes on full responsibility for behavioral disclosure. It reveals that secret variables are returned by name only because Bruno stores no value for them, and it clarifies that the return is structured JSON with specific flags. This is non-obvious context that prepares the agent for actual output.

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, using three sentences that explicitly state the purpose, the alternate usage, and an important edge case. Every sentence contributes information without redundancy, making it easy to parse and act on.

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 and the lack of an output schema, the description adequately explains what is returned and the special handling of secrets. It could potentially mention error cases or the exact JSON shape, but it is complete enough for the intended use, especially considering the schema's 100% coverage.

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 thorough descriptions for both parameters, including the meaning of 'name' and the effect of omitting it. The description adds only a note about secrets, which is more about return behavior than parameter semantics. Thus, it meets the baseline without adding significant parameter-specific value.

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

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

The description clearly states the tool reads an environment and returns structured JSON with all variables, disabled and secret flags. It additionally notes that omitting 'name' lists environments, which helps distinguish it from sibling tools like read_request or list_collections.

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 guidance on the optional name parameter, explaining that omitting it lists environments instead. It also explains the secret variable behavior, which is useful for avoiding confusion. While it doesn't explicitly name alternative tools, the usage context is sufficiently 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?

Although no annotations are provided, the description compensates by explaining that the tool returns the same shape for .bru and .yml, making the on-disk format invisible, and that a 'notes' array lists declarations the runner ignores. It also details websocket/grpc message payloads. It does not explicitly state it has no side effects, but 'read' implies read-only, and the content is sufficiently transparent for a 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 longer than average but each sentence adds value: it defines the output shape, gives usage guidance, explains websocket/grpc handling, and notes the 'notes' array. It is front-loaded with the core purpose and structured logically, though it could be slightly tightened without losing information.

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

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

Given there is no output schema, the description fully covers the return content: method, url, headers, params, body, auth, scripts, assertions, vars, settings, docs, and messages for websocket/grpc. It also explains the 'notes' array. For a single-parameter tool, this provides comprehensive context, leaving no major 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 single parameter filePath is fully described in the schema with details about absolute path and lowercasing. Since schema description coverage is 100%, the description does not need to add more, and indeed it only reiterates that both .bru and .yml are supported. No additional meaning beyond the schema is provided, so 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?

The description clearly states the tool's function: reading a single request file as structured JSON. It specifies the resource (request file) and the action (read), and differentiates from sibling tools like create_request and modify_request by focusing on reading the current state. The mention of .bru and .yml formats and the output shape adds 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 explicitly advises when to use this tool: before modify_request to see current state, and after create_request to confirm what was written. It also mentions how websocket/grpc messages are handled, guiding the agent on what to expect. This provides clear context and distinguishes it from 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 carries the transparency burden. It discloses a critical behavioral trait: 'MERGES into the environment — all other variables are preserved.' This goes beyond the schema by clarifying that removal does not replace the entire environment. It also notes 'single variable,' setting expectations for scope. However, it does not cover error handling or prerequisites (e.g., environment must exist), which could be relevant.

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, directly front-loaded with the action, and the second sentence provides essential behavioral context. Every word earns its place without unnecessary elaboration.

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 removal tool with 3 parameters and no output schema, the description covers the key aspects: what it does, the scope (single variable), and the critical side effect (preserving other variables). It does not explain return values or error behavior, but the absence of an output schema lowers the expectation. Overall, it is sufficiently complete for selecting and invoking the tool.

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

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

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds no additional parameter-level detail beyond what the schema already provides. It does relate to parameters indirectly (e.g., 'single variable' maps to 'name'), but that is behavioral context, not parameter semantics.

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

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

The description clearly states the tool's function: 'Remove a single variable from an existing Bruno environment.' It uses a specific verb ('remove'), identifies the resource ('variable'), and specifies the scope ('single' and 'existing environment'). This distinguishes it from sibling tools like set_environment_variable (which adds/updates) and update_environment (which modifies environment settings).

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 remove a variable) and includes a limitation ('single variable'), but it does not explicitly name alternatives or provide 'when not to use' guidance. The context is clear enough for an agent to select this tool over siblings, though explicit exclusions would improve it.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the operation is non-destructive to the rest of the request, explains alias handling, and discloses the side effect of dropping the now-empty script container when all scripts are removed.

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 three sentences with purpose front-loaded, followed by usage guidance and a side-effect note. It is efficient but slightly dense, combining parameter semantics with behavior in one sentence.

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

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

For a delete tool with no annotations and no output schema, the description covers the core behavior, use cases, side effects, and parameter values adequately. Minor gaps exist around error conditions or return values, but these are not critical for a removal operation.

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

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

Schema description coverage is 100%, with both parameters already having detailed descriptions. The description adds some context about canonical vs. alias scriptType values, but this is largely redundant with the schema's enum and field descriptions, so little new meaning is added.

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 (Delete) and the object (a script from a Bruno request), with specific script types listed. It also distinguishes itself from sibling tools by noting it leaves the rest of the request intact and referencing the tools that create scripts.

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 'Use this to undo or clean up a script written by create_request/modify_request/add_test_script', giving a clear when-to-use directive. It also clarifies that it removes scripts rather than the whole request, implicitly excluding delete_request.

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 — and it exceeds it. It discloses defaults (includeResponseBody=true, cookieJar=true), mutation contexts (request files that cannot be parsed are skipped vs. named ones fail the group), security properties (SSRF filtering, credential-named header values masked, websocket payloads off by default to avoid leaking secrets), edge cases (parallel request contention, bail behavior, group isolation), and failure modes (refusals, missing requests, crashed groups). It even documents timing behavior (wall-clock gaps between separate calls). This is far beyond what a schema could convey.

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 tarifficiently dense — every section (SUBSET, GROUPS, ITERATIONS, PARALLELISM, RESULTS, TRANSPORTS, STOPPING EARLY, REPORT FILES) adds necessary behavior — but it is extremely long (approximately 1,000 words) with deeply nested explanations. The use of CAPITALIZED section labels helps scannability, but the level of detail on edge cases like websocket stop reasons, engine.io PING/PONG, and gRPC details exceeds typical needs and could overwhelm an agent. It earns a 3 for being well-structured and front-loaded but loses points for length; the content is justified but the sheer volume makes it hard to extract the core purpose quickly.

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 extreme complexity (19 parameters, nested objects, multiple transports, concurrency, reporting, security) and no output schema, the description is complete. It explains return shapes (groups[] with their own summary and results, top-level summary), result fields (response_body, response_headers, capturedVariables, bail, reports), error handling (refusals, missing requests, parse errors), and omnipresent edge cases. It answers 'what happens if...' questions that an agent would need before calling. Nothing critical is left uncovered within the tool's scope.

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%, but the description adds substantial meaning beyond the schema. It explains semantics of the requests parameter with examples ('naming the same request twice runs it twice'), defines the groups parameter's isolation guarantees, clarifies iteration reporting, explains the distinction between data and dataFile behavior, details the startAfter gate semantics, and clarifies precedence rules for variables and cookieJar. This is value-added semantics that the schema's brief descriptions do not provide.

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 executes requests in a Bruno collection and runs test scripts. It explicitly enumerates core capabilities (requests, groups, iterations, parallelism, transports, reporting) and distinguishes itself from sibling tools by being the only execution tool — siblings are CRUD for collections, environments, and requests. The verb 'execute' plus resource 'Bruno collection' is specific 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 provides extensive when-to-use guidance: how to select a subset via requests list with ordered entries, when to use groups for multiple identities, when to use iterations for data-driven runs, and when to use parallel for concurrency. It explicitly states that simultaneous execution requires a single call with parallel groups, warning that separate calls are not serialized. It also names alternatives — 'get paths from list_requests or get_collection_stats' and 'Get available names from get_collection_stats' — and explicitly states when not to use certain features (e.g., 'Passing both requests and groups is REJECTED').

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 disclose behavioral traits itself. It adds the key merge behavior (other variables preserved), but omits other traits like file persistence, environment existence requirements, or secret-handling caveats (though the schema covers the secret behavior in detail).

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 clauses deliver the core purpose and the critical merge note without any filler. 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 mutation tool with a rich schema, the description plus schema provide adequate context for selection and invocation. It lacks explicit error/return behavior, but the merge note covers the main surprise.

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 descriptions for all parameters, so the description adds little parameter-specific value beyond its 'add or update' and 'single variable' framing, which is minimal.

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 ('Set') and identifies the resource ('a single variable in an existing Bruno environment'), clearly distinguishing it from sibling tools like remove_environment_variable and broader update_environment.

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 conveys clear context: add or update a single variable within an existing environment, with merging semantics. However, it does not explicitly state when to use this versus alternatives such as create_environment or remove_environment_variable.

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 carries the burden. It states that files on disk are untouched, works even if the directory is gone, and clarifies that it only affects the registry. This is transparent about side effects and safety.

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, with the main action first and the alternative explicitly stated. No redundant wording; every clause 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?

Given a simple operation with two well-documented parameters and no output schema, the description covers the purpose, the non-destructive effect, the edge case of stale entries, and the alternative tool. It is complete for an agent to understand when and how to use it.

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%, but the description adds valuable context: for collectionPath it emphasizes matching by path (not name) and advises using the path from list_collections; for workspacePath it explains the default behavior. This goes beyond the schema's basic 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 uses a specific verb ('Remove') and clearly identifies the resource (workspace registry), while explicitly distinguishing from delete_collection. It also explains the consequence (leaves files untouched) and the connection to list_collections, making it 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?

It explains when to use this tool (to stop an entry from being listed, especially for stale entries) and explicitly points to delete_collection for deletion of the collection itself. This provides clear context for choosing 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 clearly discloses the merge behavior and preservation of existing variables, which go beyond a simple 'update' label. However, it does not mention what happens if the environment does not exist, whether the operation is idempotent, or any error conditions—minor gaps given the tool's simplicity.

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 action and immediately followed by the key behavioral nuance. It is compact, easy to scan, and every word adds value. No redundancy or filler.

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

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

Given the tool's moderate complexity (3 required params, no annotations, no output schema), the description covers the essential behavior, merge semantics, and a critical distinction from a sibling. It falls slightly short of a perfect score by not specifying return values or edge-case behavior (e.g., when variables are empty), but it is sufficiently complete for typical usage.

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

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

The input schema already provides 100% coverage for all three parameters, including a description for 'variables' that states existing variables not listed are kept. The description's merge explanation mirrors the schema, adding no new parameter-level semantics. Baseline 3 is appropriate as 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 states the exact action: 'Partially update an existing Bruno environment by MERGING the provided variables into the existing ones.' It names the resource (Bruno environment) and the specific verb (update), making the purpose unambiguous. It also distinguishes itself from a sibling by explicitly contrasting with create_environment.

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 when-to-use guideline by explaining that it merges variables and preserves unlisted ones, and explicitly says 'unlike create_environment, which replaces the whole file.' This tells the agent to use this tool for partial updates while preserving existing variables, and to use create_environment when a full replacement is intended.

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