Skip to main content
Glama

Hand a brief to the Berrys agent

playground_brief_start
Idempotent

Start the Berrys agent on a brief and return at once with runId and canvasUrl; it never waits. Follow it with playground_run_events (afterSeq, optionally waitSeconds) for progress, approvals and the final response, and playground_run_diagnose if it fails. projectId defaults to the project the user has open (playground_context_current). files are node IDs of uploaded media to use as references; connectorAccountIds lets the agent read connected sources (needs connector:read). Pass conversationId to continue an earlier brief. Requires agent:start; paid steps still need approval.

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": {
      "message": "<message>"
    },
    "name": "playground_brief_start"
  }
}

Input Schema

NameRequiredDescriptionDefault
filesNoReference file attachments to include with the brief.
messageYesUser’s creative brief or steering instructions for the current run.
projectIdNoID of the Playground project chosen for this task; obtain it from project creation, an explicit project link or current context.
conversationIdNoConversation ID for filtering or continuing the associated agent work.
connectorAccountIdsNoConnected account IDs (playground_connected_sources_list) the agent may read for this brief. Only include accounts the user selected for this brief.

Output Schema

NameRequiredDescriptionDefault
nextYesSuggested next action; it does not authorize spending.
runIdYes
statusYes
canvasUrlYes
projectIdYes
nextAfterSeqYes
conversationIdYes
retry_after_secondsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare the mutation/idempotency profile, but the description adds facts they cannot express: the call never waits, it returns runId and canvasUrl immediately, it requires agent:start, connector access requires connector:read, and paid steps still need approval. The only gap is that it does not say what happens if a run is started with a stale conversationId or how the idempotency hint behaves on retry.

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?

The async, non-blocking behavior and the return values are front-loaded in the first clause, then follow-up tools, then parameters, then permissions. Every clause carries a distinct fact with no redundant restatement of the title or schema.

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 an async kickoff tool with five parameters and an output schema, this covers purpose, non-blocking behavior, return identifiers, continuation via conversationId, scope requirements, and the approval gate. Nothing an agent needs in order to invoke it correctly is missing.

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 100%, so the schema carries the baseline, but the description still adds real meaning: projectId defaults to the project the user has open (playground_context_current), files are node IDs of uploaded media rather than raw attachments, and connectorAccountIds gates on connector:read. That goes beyond the schema text, though it stops short of clarifying message-length or file-count limits.

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?

"Start the Berrys agent on a brief and return at once with runId and canvasUrl" gives a specific verb (start), a specific resource (agent run on a brief), and the return shape. The follow-up sentence explicitly separates it from playground_run_events and playground_run_diagnose, so an agent can route without opening a schema.

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?

It names the alternatives and the conditions that select them: playground_run_events (afterSeq, optionally waitSeconds) for progress/approvals/final response, and playground_run_diagnose if the run fails. conversationId is also scoped to 'continue an earlier brief', which tells the agent when to reuse a run lineage.

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.