Skip to main content
Glama
Sign In
bale-mcp

bale-mcp

by sepehr071
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Bot: new messages

bot_get_new_messages

Retrieve unread messages sent to your Bale bot since the last check, oldest first, then mark them as read. Reply using chat_id; download media with file_id.

Instructions

Get messages people sent the bot since the last check, from all chats, oldest first, and mark them read.

Each message has chat_id (reply with it), from, kind (text, photo, button, ...), text, and file_id for media (see bot_download_file). unread_left counts the rest. Fails while a webhook is set (see bot_get_webhook_info).

Input Schema

NameRequiredDescriptionDefault
limitNoMax messages.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.2.0
    • changedInput schema / properties / limit / default
      Previous value: -50New value: +20
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • removedInput schema / title
      Removed value: -"bot_get_new_messagesArguments"
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "title": "bot_get_new_messagesDictOutput",
-  "type": "object"
-}New value: +null
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

Goes beyond annotations by disclosing why readOnlyHint=false: the call marks messages read, an irreversible state change. It also surfaces a non-obvious failure precondition (webhook configured) and the delivery order, none of which the annotations express. No contradiction with readOnlyHint=false / destructiveHint=false.

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 purpose, scope, ordering and side effect in one sentence, then response fields, then the failure condition. No filler; each sentence carries distinct information an agent needs.

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?

With no output schema, the description compensates by enumerating the response fields (chat_id, from, kind, text, file_id, unread_left) and pointing to bot_download_file for media. Given a 1-param, no-required-param tool, nothing needed 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.

Parameters3/5

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

One parameter with 100% schema description coverage plus a documented default and range, so the schema already carries the meaning. The description does not mention 'limit' or explain truncation behavior beyond 'unread_left counts the rest', which is baseline-adequate.

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+resource with scope and semantics: 'Get messages people sent the bot since the last check, from all chats, oldest first, and mark them read.' The polling scope ('since the last check') and ordering distinguish it clearly from siblings like bot_search_messages and bot_read_chat.

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?

Implies the polling use case ('since the last check') and gives a concrete precondition — 'Fails while a webhook is set (see bot_get_webhook_info)' — which routes the agent to a sibling for diagnostics. It does not explicitly contrast with bot_search_messages or bot_read_chat, so the when-not is only partial.

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

Deploy Server

Other Tools