Skip to main content
Glama

Message an agent

message_agent
Destructive

Send a message to one of the user's own agents by its handle (the name after the @ on its page) and start a run with it. Use this when the user asks you to hand something to a named agent: '@research, what changed at Acme?'. It returns at once with a trace_id; the agent's answer takes a minute or more, so read it later with agent_reply. Pass conversation_id to keep the exchange in one thread.

Input Schema

NameRequiredDescriptionDefault
textYesWhat to ask the agent, in the user's own words.
handleYesThe agent's handle, with or without the leading @.
conversation_idNoThe chat thread to post into. Leave it out to start a new one; the result names the thread used.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior4/5

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

Adds real value beyond annotations: it discloses that the call is asynchronous, returns at once with a trace_id, and that the real answer arrives a minute or more later — critical for avoiding a premature second call. However, the annotations mark destructiveHint=true and the description never explains what side effect makes it destructive or whether a run can be cancelled or undone.

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?

Three sentences, front-loaded with the action and the routing condition, followed by the async-return caveat and the threading tip. Every sentence carries distinct information; nothing is repeated from the schema or annotations.

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?

With no output schema, the description correctly fills the gap by describing the return (trace_id) and the deferred answer pattern, and it points to the sibling that reads the result. The one omission is any account of the destructive side effect the annotations flag, which leaves the agent without a risk picture.

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 already defines all three parameters; the baseline would be 3. The description goes slightly further by explaining the intent behind conversation_id (thread continuity) and clarifying the handle format, giving the agent a reason to set the optional parameter rather than just a definition.

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 — send a message to one of the user's own agents by handle and start a run — and disambiguates from the sibling agent_reply by name. An agent can tell immediately this is the 'kick off' tool, not the 'read result' tool.

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?

Gives an explicit trigger condition plus a concrete example ('@research, what changed at Acme?') and names the follow-up alternative, agent_reply, for retrieving the answer. No inference required about when to pick this tool.

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.