Skip to main content
Glama

Run a Promoter Brief

run_brief

Start a Promoter Brief for a booking question that names an artist and a market, e.g. 'Should I book Wet Leg in Denver in October?' (a venue, date or capacity can be included). Takes about five minutes and uses one of the promoter's briefs (free, the plan's allowance, or one bought in a pack; not charged if the run needs more input or fails). Returns a job_id immediately — poll get_brief_job every 45 seconds. force_low_confidence=true runs anyway when a previous attempt reported thin data; force_refresh=true regenerates instead of reusing data from the last 24 hours. use_profile=false leaves the promoter's saved booking profile (home market, rooms, genres, guarantee range) out of the brief — use it when the question is asked on someone else's behalf or about a market the promoter doesn't book in.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "run_brief"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYes
use_profileNo
force_refreshNo
force_low_confidenceNo

Output Schema

NameRequiredDescriptionDefault
noteYes
quotaNoThe plan allowance after this run. Absent when the run used a purchased brief.
job_idYes
statusNorunning
purchased_briefsNoSet when this run used a purchased brief: what's left after it.
estimated_secondsYes
poll_after_secondsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / use_profile
      Added value: +{
      +  "default": true,
      +  "title": "Use Profile",
      +  "type": "boolean"
      +}
  2. Changed1 schema field changed
    • changedOutput schema / $defs / Quota / properties / scope / description
      Previous value: -"'user' for Scout, 'team' for Buyer/Company"New value: +"'user' for free accounts and Scout, 'team' for Buyer/Company"
  3. Changed3 schema fields changed
    • addedOutput schema / $defs / PurchasedBriefs
      Added value: +{
      +  "properties": {
      +    "expires_at": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "description": "The whole purchased balance expires at this time (12 months after the last purchase)",
      +      "title": "Expires At"
      +    },
      +    "remaining": {
      +      "description": "Briefs bought in packs that can still be used. Spent only after the plan's allowance runs out.",
      +      "title": "Remaining",
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "remaining"
      +  ],
      +  "title": "PurchasedBriefs",
      +  "type": "object"
      +}
    • addedOutput schema / properties / purchased_briefs
      Added value: +{
      +  "anyOf": [
      +    {
      +      "$ref": "#/$defs/PurchasedBriefs"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Set when this run used a purchased brief: what's left after it."
      +}
    • addedOutput schema / properties / quota / description
      Added value: +"The plan allowance after this run. Absent when the run used a purchased brief."
  4. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only declare it is a non-read-only, open-world, non-idempotent, non-destructive call; the description adds substantial context beyond that: ~5 minute runtime, credit consumption from the free/plan/pack allowance, no charge on failure or insufficient input, asynchronous job_id return, 24-hour data reuse, and the confidence-override behavior. That is exactly the kind of billing, latency, and async semantics annotations cannot express.

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?

Front-loaded with the purpose and example, then cost, then async behavior, then flag semantics — a sensible order. It is dense and leans on parentheticals, reading as one continuous block, which costs a little scannability, but no sentence is filler.

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

Completeness5/5

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

For a credit-consuming async job tool this covers cost, timing, failure charging, polling cadence, data-freshness reuse, and profile-exclusion rationale. With an output schema present it correctly does not waste space describing return fields beyond the immediate job_id.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must carry the load, and it does: query content requirements with an example, the three boolean flags each explained with the situation that selects them, and the default-relevant behavior of use_profile. No parameter is left as a bare name.

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 ('Start a Promoter Brief') and pins down the required input shape with a concrete example question naming artist and market, plus optional venue/date/capacity. An agent can immediately distinguish this from get_brief and get_brief_job, which are named in the text.

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

Usage Guidelines5/5

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

Explicit usage conditions are given: use_profile=false for questions asked on someone else's behalf or outside the promoter's markets, force_low_confidence=true when a prior attempt reported thin data, force_refresh=true to bypass the 24-hour data reuse. It also names the correct follow-up (poll get_brief_job every 45 seconds), so the agent knows both when to call it and what to do next.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources