Skip to main content
Glama
Sign In

Brand Design Ltd.

by ltd.branddesign
OverviewDiscussionsAdmin

accept_offer

Idempotent

Accept the offer on behalf of the buyer. Needs credentials. This locks the billing identity, the offer version and the hash of the terms as they stand at this moment. A later change to the website cannot pass for what was agreed. Errors: OFFER_CHANGED (409) if the offer or the terms changed since you read them; read order_status and use the new values. OFFER_EXPIRED (409) 30 days after the order. MANUAL_OFFER_REQUIRED (409) while a person has not priced the service yet.

Input Schema

NameRequiredDescriptionDefault
orderYesThe order id returned by create_order.
secretNoRequired unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The secret returned by register_agent.
billingYesThe buyer as it will appear on the invoice and the contract. For type company, company, registration and representative are also required. For type person, leave out company, registration, vat and representative. No other keys are accepted.
clientIdNoRequired unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The clientId returned by register_agent.
termsHashYesSHA-256 of the terms page in the language of the order: offer.terms.<language>.hash from the order, copied exactly. Sending it confirms that the buyer accepts those terms.
accessTokenYesThe accessToken returned by create_order.
offerVersionYesoffer.version from the order, copied exactly.
immediateStartNoNatural persons only: true when the buyer expressly asks the work to start within the 14-day withdrawal period and acknowledges losing the right of withdrawal once the service is fully performed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / immediateStart
      Added value: +{
+  "description": "Natural persons only: true when the buyer expressly asks the work to start within the 14-day withdrawal period and acknowledges losing the right of withdrawal once the service is fully performed.",
+  "type": "boolean"
+}
  2. Changed12 schema fields changed
    • addedInput schema / properties / accessToken / description
      Added value: +"The accessToken returned by create_order."
    • addedInput schema / properties / billing / additionalProperties
      Added value: +false
    • changedInput schema / properties / billing / description
      Previous value: -"type (person or company), fullName or company with eik, email, country, city, address, phone."New value: +"The buyer as it will appear on the invoice and the contract. For type company, company, registration and representative are also required. For type person, leave out company, registration, vat and representative. No other keys are accepted."
    • addedInput schema / properties / billing / if
      Added value: +{
+  "properties": {
+    "type": {
+      "const": "company"
+    }
+  }
+}
    • addedInput schema / properties / billing / properties
      Added value: +{
+  "address": {
+    "maxLength": 250,
+    "minLength": 3,
+    "type": "string"
+  },
+  "city": {
+    "maxLength": 100,
+    "minLength": 1,
+    "type": "string"
+  },
+  "company": {
+    "description": "Company only. Registered name.",
+    "maxLength": 200,
+    "minLength": 2,
+    "type": "string"
+  },
+  "country": {
+    "description": "ISO 3166-1 alpha-2 code, for example BG.",
+    "pattern": "^[A-Za-z]{2}$",
+    "type": "string"
+  },
+  "email": {
+    "maxLength": 254,
+    "type": "string"
+  },
+  "fullName": {
+    "description": "Full name of the buyer, or of the contact person for a company.",
+    "maxLength": 150,
+    "minLength": 3,
+    "type": "string"
+  },
+  "phone": {
+    "description": "Optional.",
+    "maxLength": 40,
+    "minLength": 5,
+    "type": "string"
+  },
+  "registration": {
+    "description": "Company only. Company registration number; for country BG the 9- or 13-digit EIK.",
+    "maxLength": 40,
+    "minLength": 4,
+    "type": "string"
+  },
+  "representative": {
+    "description": "Company only. The person who legally represents the company.",
+    "maxLength": 150,
+    "minLength": 3,
+    "type": "string"
+  },
+  "type": {
+    "enum": [
+      "person",
+      "company"
+    ],
+    "type": "string"
+  },
+  "vat": {
+    "description": "Company only. Optional VAT number.",
+    "maxLength": 40,
+    "minLength": 4,
+    "type": "string"
+  }
+}
    • addedInput schema / properties / billing / required
      Added value: +[
+  "type",
+  "fullName",
+  "email",
+  "country",
+  "city",
+  "address"
+]
    • addedInput schema / properties / billing / then
      Added value: +{
+  "required": [
+    "company",
+    "registration",
+    "representative"
+  ]
+}
    • changedInput schema / properties / clientId / description
      Previous value: -"Your client identifier, if not sent in the Authorization header."New value: +"Required unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The clientId returned by register_agent."
    • addedInput schema / properties / offerVersion / description
      Added value: +"offer.version from the order, copied exactly."
    • addedInput schema / properties / order / description
      Added value: +"The order id returned by create_order."
    • changedInput schema / properties / secret / description
      Previous value: -"Your secret, if not sent in the Authorization header."New value: +"Required unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The secret returned by register_agent."
    • addedInput schema / properties / termsHash / description
      Added value: +"SHA-256 of the terms page in the language of the order: offer.terms.<language>.hash from the order, copied exactly. Sending it confirms that the buyer accepts those terms."
  3. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare the mutation profile (readOnly=false, destructive=false, idempotent=true), and the description adds real context on top: it pins the billing identity, offer version and terms hash at acceptance time so a later website change 'cannot pass for what was agreed.' It also enumerates three concrete 409 failure modes with their causes and time windows (OFFER_CHANGED, OFFER_EXPIRED at 30 days, MANUAL_OFFER_REQUIRED), which the annotations cannot convey.

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

Conciseness5/5

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

Front-loaded with the action, then credentials, then the locking semantics, then a compact error list. Every sentence carries non-redundant information and there is no filler.

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?

Strong coverage for an 8-parameter mutation tool with a nested billing object and no output schema: mutation effects, credentials and error semantics are all covered. It does not say what a successful acceptance returns or what the next step in the flow is (e.g. start_payment), which leaves a small gap given there is no output schema to fall back on.

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 description coverage is 100%, so the schema already documents every parameter and the baseline is 3. The description goes beyond it by explaining the *meaning* of offerVersion and termsHash — they lock the agreed version and terms at this moment — and adds the credential requirement for accessToken/secret/clientId.

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?

States a specific verb and resource with scope: 'Accept the offer on behalf of the buyer.' Combined with the sibling list (create_order, order_status, start_payment), an agent can immediately tell that this is the terminal commitment action rather than an order-creation or payment step.

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?

Gives the credential prerequisite ('Needs credentials') and routes the agent on the primary failure path: on OFFER_CHANGED, 'read order_status and use the new values,' explicitly naming the sibling tool to fall back to. It does not state when not to use this tool or any precondition about waiting for a priced offer beyond the MANUAL_OFFER_REQUIRED error, so it stops short of full 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.

All Brand Design Ltd. toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources