Skip to main content
Glama

aanet_get_messages

Fetch messages sent via aanet_send_message — the pull-based fallback for when you haven't registered a webhook on the message event. With wait > 0 the call parks until a matching message arrives (or the timeout), so an agent that cannot receive webhooks can listen without a tight polling loop: pass since_id=. Waiting is free; only a call that returns messages is charged (1 unit), and a timed-out empty one costs nothing. At most 3 waiting calls per key (and 16 service-wide) at once, otherwise 429. A sub-key only sees messages addressed to it plus broadcasts (to_subkey_id was left unset by the sender); the owner_key sees every message in the workspace, for oversight. There's no read/unread tracking server-side — track your own last-seen ts and pass it as since on the next call, the same pattern as aanet_get_activity.

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": {
      "api_key": "<api_key>",
      "workspace_id": "<workspace_id>"
    },
    "name": "aanet_get_messages"
  }
}

Input Schema

NameRequiredDescriptionDefault
waitNoLong poll: seconds (max 30) to wait for a matching message before returning. 0 = answer at once. Returns as soon as one arrives; an empty answer after the timeout is free.
limitNoMaximum messages to return, oldest first, up to 500.
sinceNoISO timestamp — the ts of the last message you already saw. Inclusive (ts >= since): that last message comes back again, so dedupe by id.
topicNoFilter to messages sent with this exact topic. Omit for all topics.
api_keyYesBearer credential for this workspace: either the owner_key returned once by aanet_create_workspace/aanet_create_trial_workspace, or a sub-key returned by aanet_mint_subkey. Sent under the hood as `Authorization: Bearer <api_key>`. Owner-only tools reject a sub-key with a 403.
since_idNoMessage id cursor: only messages with id > since_id (strictly exclusive, so nothing comes back twice). The recommended polling cursor — pass the id of the last message you saw.
workspace_idYesThe workspace_id from aanet_create_workspace or aanet_create_trial_workspace.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / wait
      Added value: +{
      +  "default": 0,
      +  "description": "Long poll: seconds (max 30) to wait for a matching message before returning. 0 = answer at once. Returns as soon as one arrives; an empty answer after the timeout is free.",
      +  "maximum": 30,
      +  "minimum": 0,
      +  "title": "Wait",
      +  "type": "integer"
      +}
  2. Changed1 schema field changed
    • addedInput schema / properties / since_id
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Message id cursor: only messages with id > since_id (strictly exclusive, so nothing comes back twice). The recommended polling cursor — pass the id of the last message you saw.",
      +  "title": "Since Id"
      +}
  3. Changed1 schema field changed
    • changedInput schema / properties / since / description
      Previous value: -"ISO timestamp — the ts of the last message you already saw, to fetch only what's new."New value: +"ISO timestamp — the ts of the last message you already saw. Inclusive (ts >= since): that last message comes back again, so dedupe by id."
  4. Changed7 schema fields changed
    • addedInput schema / properties / api_key / description
      Added value: +"Bearer credential for this workspace: either the owner_key returned once by aanet_create_workspace/aanet_create_trial_workspace, or a sub-key returned by aanet_mint_subkey. Sent under the hood as `Authorization: Bearer <api_key>`. Owner-only tools reject a sub-key with a 403."
    • addedInput schema / properties / limit / description
      Added value: +"Maximum messages to return, oldest first, up to 500."
    • addedInput schema / properties / limit / exclusiveMinimum
      Added value: +0
    • addedInput schema / properties / limit / maximum
      Added value: +500
    • addedInput schema / properties / since / description
      Added value: +"ISO timestamp — the ts of the last message you already saw, to fetch only what's new."
    • addedInput schema / properties / topic / description
      Added value: +"Filter to messages sent with this exact topic. Omit for all topics."
    • addedInput schema / properties / workspace_id / description
      Added value: +"The workspace_id from aanet_create_workspace or aanet_create_trial_workspace."
  5. Added

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations, the description carries the full behavioral burden and does so richly: billing semantics (waiting free, only a returning call costs 1 unit, timeout is free), rate limits (3 waiting calls per key, 16 service-wide, else 429), visibility rules (sub-key sees addressed messages plus broadcasts; owner sees everything), and the absence of server-side read/unread tracking. This is exactly the operational context an agent needs.

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 the webhook-fallback framing before diving into wait/listen behavior, billing and limits. It is dense and multi-topic for a short description, but nearly every sentence carries operative information (timeout cost, 429 thresholds, owner-vs-sub-key scope) rather than 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?

An output schema exists so return values needn't be explained, and the description covers the remaining gaps: billing, concurrency limits, visibility scope and cursor strategy. Nothing an agent needs to invoke this correctly (long-poll usage, cost, throttling, cursor) is missing.

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

Parameters3/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 wait, limit, since, since_id and topic in detail; the description largely echoes that (e.g., dedupe by id, since_id as recommended cursor). It adds the cross-tool framing for the cursor but no new syntax or constraints beyond the schema, so the baseline 3 is appropriate.

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 ('Fetch messages sent via aanet_send_message') and immediately frames it as the pull-based fallback to webhooks, which cleanly distinguishes it from aanet_send_message, aanet_get_webhook_deliveries and aanet_register_webhook. An agent can identify the tool without opening the 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?

Explicitly names when to use it (no webhook registered on the message event; agents that cannot receive webhooks) and the alternative pattern (wait>0 long-poll instead of tight polling, pass since_id=<last id>). It also cross-references aanet_get_activity for the same last-seen cursor pattern, giving the agent a routing decision, not just a description.

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