Skip to main content
Glama

Modify Request

modify_request

Update a Bruno API request file by merging only the fields you provide, preserving all others. Edit URLs, headers, auth, body, scripts, assertions, or settings; supports rename, file uploads, and multipart data in one call.

Instructions

Update an existing Bruno request file with partial-merge semantics. Only provided fields are updated; all other fields are preserved. Supports multipart/form-data with file uploads and per-part contentType. Inline scripts REPLACE the existing script of the same type by default (idempotent — repeated calls do not accumulate duplicate blocks); pass scriptMode:"append" to concatenate instead. Use remove_script to clear a script entirely. RENAMING: name and filename are independent, as they are in Bruno itself — name changes the request's name inside the file and filename moves the file. Pass both to keep them in step, and read the new path back from the response.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNo
authNo
bodyNo
grpcNogRPC-only fields. Applies to kind "grpc" and is refused otherwise. Headers given for a gRPC request are written as metadata, which is that transport's only header surface.
nameNoThe request's name inside the file. Does NOT rename the file — pass filename for that.
varsNo
queryNo
assertNoReplaces the whole assert block. Omit to leave existing assertions untouched.
methodNo
headersNo
scriptsNoInline scripts to persist with the request. Keys: pre-request, post-response, tests (aliases before-request/after-response accepted). Avoids a separate add_test_script call. IMPORTANT for tests/post-response: only assertions inside a test() block are reported. Write test("status is 200", function() { expect(res.getStatus()).to.equal(200); }); — a bare expect() at the top level still runs, but a passing one records nothing, so run_collection reports "tests": [] and the request looks green with no assertions. Available in scripts: res.getStatus()/getStatusText()/getHeader(name)/getHeaders()/getBody()/getResponseTime(), res.getStopReason()/getCloseCode()/getSessionTruncated() on a websocket request, which report the same session outcome the result does (all null or false on an HTTP response, which has no session), bru.setVar(name, value)/getVar(name)/getEnvVar(name)/hasEnvVar(name), and expect(actual) with .to.equal/.contain/.include, .to.have.property/.lengthOf, .to.be.a/.an, .to.be.above/.below/.at.least/.at.most (aliases .gt/.lt/.gte/.lte/.greaterThan/.lessThan), .to.be.within(min, max), .to.be.oneOf([...]), .to.match(/re/), .to.startWith/.endWith, .to.be.true/.false/.null/.undefined/.empty/.json,and .to.not.* negations. VARIABLES: bru.getVar(name) resolves environment and collection variables as well as anything a script set, so an environment variable needs no shadow copy to be readable. bru.getEnvVar(name) is narrower on purpose: it reads the environment layer only, so a runtime variable of the same name does not shadow it. There is no setEnvVar — nothing here writes an environment file. RETURN TYPE: res.getBody() returns the response already parsed into a JS object/array when the Content-Type is application/json or a +json type (raw text otherwise). Access fields directly — res.getBody().field — and do NOT JSON.parse() it, which throws SyntaxError: "[object Object]" is not valid JSON.
filePathYesAbsolute path to the .yml or .bru request file to modify. Get from list_requests or get_collection_stats.
filenameNoRenames the file, keeping it in its own folder. Basename only, no path separators. The extension is optional and must match the collection's format if given, since a collection carries one format only. Refused if another file of that name already exists. The new path comes back in the response; use it as filePath from then on, because the old one is gone.
settingsNoRequest-level settings: transport behaviour (timeouts, redirects, URL encoding), not payload. What reaches the file depends on the dialect, because Bruno's own two writers differ: a .yml request always carries a fully resolved settings block whether or not you pass one, while a .bru request carries only what you supply. On modify_request the fields are merged individually over the existing block, so setting one does not clear the rest. Note the encodeUrl field: in .bru, creating a block at all changes the URL-encoding default.
websocketNoWebSocket-only fields. Applies to kind "websocket" and is refused otherwise.
pathParamsNoReplaces the declared path parameters; query parameters are left alone.
scriptModeNoHow to write the scripts field. "replace" (default) overwrites the existing script of each provided type, so calling modify_request repeatedly is idempotent. "append" concatenates onto the existing script, which accumulates blocks across calls. Each script type has its own slot in both .bru and .yml, so replacing one leaves the others untouched. One exception on .yml: supplying post-response and tests together in a single call still merges both into the after-response slot, so write the tests script in its own call to keep it in the tests slot.replace

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv2.4.0
    • changedInput schema / properties / body / properties / formData / description
      Previous value: -"multipart/form-data parts, for body.type \"form-data\" or \"multipart-form\"."New value: +"Key/value parts, and the only field here that carries them: multipart/form-data parts for body.type \"form-data\" or \"multipart-form\", and the pairs of a \"form-urlencoded\" body, which read_request returns under formUrlEncoded rather than here (a form-urlencoded body can also be given as an encoded string in `content`). The per-entry type and contentType describe a multipart part and are rejected on a form-urlencoded body, where every pair is text and neither field is stored: pass type \"file\" or a contentType there and the call fails rather than writing a request that drops them."
    • addedInput schema / properties / filename
      Added value: +{
      +  "description": "Renames the file, keeping it in its own folder. Basename only, no path separators. The extension is optional and must match the collection's format if given, since a collection carries one format only. Refused if another file of that name already exists. The new path comes back in the response; use it as filePath from then on, because the old one is gone.",
      +  "type": "string"
      +}
    • addedInput schema / properties / name / description
      Added value: +"The request's name inside the file. Does NOT rename the file — pass filename for that."
    • changedInput schema / properties / scripts / description
      Previous value: -"Inline scripts to persist with the request. Keys: pre-request, post-response, tests (aliases before-request/after-response accepted). Avoids a separate add_test_script call. IMPORTANT for tests/post-response: only assertions inside a test() block are reported. Write test(\"status is 200\", function() { expect(res.getStatus()).to.equal(200); }); — a bare expect() at the top level still runs, but a passing one records nothing, so run_collection reports \"tests\": [] and the request looks green with no assertions. Available in scripts: res.getStatus()/getStatusText()/getHeader(name)/getHeaders()/getBody()/getResponseTime(), bru.setVar(name, value)/getVar(name), and expect(actual) with .to.equal/.contain/.include, .to.have.property/.lengthOf, .to.be.a/.an, .to.be.above/.below/.at.least/.at.most (aliases .gt/.lt/.gte/.lte/.greaterThan/.lessThan), .to.be.within(min, max), .to.be.oneOf([...]), .to.match(/re/), .to.startWith/.endWith, .to.be.true/.false/.null/.undefined/.empty/.json,and .to.not.* negations. RETURN TYPE: res.getBody() returns the response already parsed into a JS object/array when the Content-Type is application/json or a +json type (raw text otherwise). Access fields directly — res.getBody().field — and do NOT JSON.parse() it, which throws SyntaxError: \"[object Object]\" is not valid JSON."New value: +"Inline scripts to persist with the request. Keys: pre-request, post-response, tests (aliases before-request/after-response accepted). Avoids a separate add_test_script call. IMPORTANT for tests/post-response: only assertions inside a test() block are reported. Write test(\"status is 200\", function() { expect(res.getStatus()).to.equal(200); }); — a bare expect() at the top level still runs, but a passing one records nothing, so run_collection reports \"tests\": [] and the request looks green with no assertions. Available in scripts: res.getStatus()/getStatusText()/getHeader(name)/getHeaders()/getBody()/getResponseTime(), res.getStopReason()/getCloseCode()/getSessionTruncated() on a websocket request, which report the same session outcome the result does (all null or false on an HTTP response, which has no session), bru.setVar(name, value)/getVar(name)/getEnvVar(name)/hasEnvVar(name), and expect(actual) with .to.equal/.contain/.include, .to.have.property/.lengthOf, .to.be.a/.an, .to.be.above/.below/.at.least/.at.most (aliases .gt/.lt/.gte/.lte/.greaterThan/.lessThan), .to.be.within(min, max), .to.be.oneOf([...]), .to.match(/re/), .to.startWith/.endWith, .to.be.true/.false/.null/.undefined/.empty/.json,and .to.not.* negations. VARIABLES: bru.getVar(name) resolves environment and collection variables as well as anything a script set, so an environment variable needs no shadow copy to be readable. bru.getEnvVar(name) is narrower on purpose: it reads the environment layer only, so a runtime variable of the same name does not shadow it. There is no setEnvVar — nothing here writes an environment file. RETURN TYPE: res.getBody() returns the response already parsed into a JS object/array when the Content-Type is application/json or a +json type (raw text otherwise). Access fields directly — res.getBody().field — and do NOT JSON.parse() it, which throws SyntaxError: \"[object Object]\" is not valid JSON."
    • addedInput schema / properties / settings / properties / keepAliveInterval
      Added value: +{
      +  "description": "WebSocket requests only: milliseconds between the pings Bruno sends to hold the connection open, where 0 means never. A .yml WebSocket request always carries the key and records an unset value as 0, so this is how you change it; on .bru it is written only when you supply it. It is read back by read_request either way. This server's own runner sends no periodic pings of its own — it answers a ping the peer sends and records both frames — so the value is carried for Bruno rather than acted on here.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedInput schema / properties / settings / properties / timeout / description
      Previous value: -"Milliseconds, capping two separate things. The HTTP request itself, which defaults to 30000ms when unset. And the per-script budget shared by pre-request, post-response and tests code, including time spent in bru.sleep, setTimeout and setInterval, which defaults to 5000ms when unset — a script that waits longer than its budget is aborted, and setting this is the only way to lift that 5000ms cap. 0 means no timeout at all."New value: +"Milliseconds, capping two separate things — and 0 does not mean the same to both. The request itself: 0 means no deadline at all, and the 30000ms default is reached only by a request whose file carries no timeout key, which a .yml request written here never does (that dialect always writes a fully resolved settings block, and an unset timeout is written as 0). So pass a positive value if you want a deadline on a .yml request. And the per-script budget shared by pre-request, post-response and tests code, including time spent in bru.sleep, setTimeout and setInterval: that one cannot be switched off, so 0 and an unset timeout both leave it at its 5000ms default, and a positive value is the only way to raise it. A script that waits longer than its budget is aborted."
    • changedInput schema / properties / websocket / properties / messages / items / properties / selected / description
      Previous value: -"Whether the message is sent. Defaults to true, and is always written, because a .yml message without it is one Bruno will not send. A false is refused in a .bru collection, which cannot record it."New value: +"Whether the message is sent. Defaults to true, and is written for every message that is sent, because a message without it is one Bruno will not send. A false is written as such in .yml; .bru can only record it by omitting the flag, which reads back as absent rather than false."
  2. Changed2 schema fields changedv2.3.0
    • addedInput schema / properties / grpc
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "gRPC-only fields. Applies to kind \"grpc\" and is refused otherwise. Headers given for a gRPC request are written as metadata, which is that transport's only header surface.",
      +  "properties": {
      +    "messages": {
      +      "description": "Request messages. A unary call uses the first.",
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "content": {
      +            "description": "The payload as JSON text. Empty content is written as {}, as Bruno writes it.",
      +            "type": "string"
      +          },
      +          "title": {
      +            "description": "Name of the message. Defaults to \"message N\" by position, as Bruno does.",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "content"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "method": {
      +      "description": "The fully qualified RPC method, e.g. \"/greet.Greeter/SayHello\". Not an HTTP verb, which is why it is here and not in the top-level method argument.",
      +      "type": "string"
      +    },
      +    "methodType": {
      +      "description": "The RPC shape. All four are written, because Bruno writes all four; note that this server can only run \"unary\" today, so the others author a request Bruno can send and run_collection will refuse.",
      +      "enum": [
      +        "unary",
      +        "client-streaming",
      +        "server-streaming",
      +        "bidi-streaming"
      +      ],
      +      "type": "string"
      +    },
      +    "protoPath": {
      +      "description": "The .proto file describing the service, relative to the collection. Must already exist inside the collection: a path resolving outside it is refused, symlinks included, as is one whose imports leave it however many hops in. Stored relative to the collection whichever spelling is given, so the request survives being cloned elsewhere.",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / websocket
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "WebSocket-only fields. Applies to kind \"websocket\" and is refused otherwise.",
      +  "properties": {
      +    "messages": {
      +      "description": "Messages sent in order once the socket is open.",
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "content": {
      +            "description": "The payload, sent verbatim after variable substitution.",
      +            "type": "string"
      +          },
      +          "selected": {
      +            "description": "Whether the message is sent. Defaults to true, and is always written, because a .yml message without it is one Bruno will not send. A false is refused in a .bru collection, which cannot record it.",
      +            "type": "boolean"
      +          },
      +          "title": {
      +            "description": "Name of the message. Defaults to \"message N\" by position, as Bruno does.",
      +            "type": "string"
      +          },
      +          "type": {
      +            "description": "How Bruno's editor should treat the payload: text, json or xml. Nothing validates it, and every frame is sent as text — there is no binary send path.",
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "content"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    }
      +  },
      +  "type": "object"
      +}
  3. First observedv2.2.1

TDQS

A4.3/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.