set_chat_description

Instructions

Implementation Reference

• aiogram_mcp/tools/chats.py:230-258 (handler)

  The tool handler function that executes set_chat_description logic: validates chat permission, applies rate limiting, calls bot.set_chat_description, and returns OkResult.

  async def set_chat_description(chat_id: int, description: str) -> OkResult:
      """Change the description of a group or channel."""
      if not ctx.is_chat_allowed(chat_id):
          result = OkResult(ok=False, error=f"Chat {chat_id} is not allowed.")
          if ctx.audit_logger:
              ctx.audit_logger.log(
                  "set_chat_description",
                  {"chat_id": chat_id, "description": description},
                  result.ok,
                  result.error,
              )
          return result
  
      try:
          if ctx.rate_limiter:
              await ctx.rate_limiter.acquire()
          await ctx.bot.set_chat_description(chat_id=chat_id, description=description)
          result = OkResult(ok=True)
      except (TelegramBadRequest, TelegramForbiddenError) as exc:
          result = OkResult(ok=False, error=str(exc))
  
      if ctx.audit_logger:
          ctx.audit_logger.log(
              "set_chat_description",
              {"chat_id": chat_id, "description": description},
              result.ok,
              result.error,
          )
      return result

• aiogram_mcp/models.py:15-18 (schema)

  The response schema (OkResult) used by set_chat_description, inheriting ToolResponse with ok/error fields.

  class OkResult(ToolResponse):
      """Result for tools that return only ok/error (delete, pin, etc.)."""
  
      pass

• aiogram_mcp/models.py:8-12 (schema)

  Base pydantic model for all tool responses, providing the ok and error fields.

  class ToolResponse(BaseModel):
      """Base model for all tool results. ok=True on success, ok=False with error on failure."""
  
      ok: bool
      error: str | None = None

• aiogram_mcp/tools/chats.py:227-258 (registration)

  Registration of the tool via @mcp.tool decorator, guarded by allowed_tools check, within register_chat_tools().

  if allowed_tools is None or "set_chat_description" in allowed_tools:
  
      @mcp.tool
      async def set_chat_description(chat_id: int, description: str) -> OkResult:
          """Change the description of a group or channel."""
          if not ctx.is_chat_allowed(chat_id):
              result = OkResult(ok=False, error=f"Chat {chat_id} is not allowed.")
              if ctx.audit_logger:
                  ctx.audit_logger.log(
                      "set_chat_description",
                      {"chat_id": chat_id, "description": description},
                      result.ok,
                      result.error,
                  )
              return result
  
          try:
              if ctx.rate_limiter:
                  await ctx.rate_limiter.acquire()
              await ctx.bot.set_chat_description(chat_id=chat_id, description=description)
              result = OkResult(ok=True)
          except (TelegramBadRequest, TelegramForbiddenError) as exc:
              result = OkResult(ok=False, error=str(exc))
  
          if ctx.audit_logger:
              ctx.audit_logger.log(
                  "set_chat_description",
                  {"chat_id": chat_id, "description": description},
                  result.ok,
                  result.error,
              )
          return result

• aiogram_mcp/permissions.py:47-47 (helper)

  Permission mapping assigning set_chat_description to MODERATION level.

  "set_chat_description": PermissionLevel.MODERATION,