On My Radar
On this page

Guides Agents and MCP

MCP tools for reading and searching

Reference for the eleven MCP tools that read radars, search blips, list tags, read the drop box, and fetch emails and attachments.

Updated October 30, 2026 · Checked against On My Radar build 2c4905d

These eleven tools only read. They are the ones an agent calls first: load a radar, search across everything you can see, open one blip in full, sort the drop box, and fetch an email or an attachment. Ids, cursors and scopes are explained in the MCP reference overview.

Reading a radar

read_radar

Loads a radar and its blips in one call. This is the fastest way to bring everything you have thrown at a subject into an agent before it acts. To list your radars first, use list_radars in radars and templates.

  • Scope: radars:read. Read-only.
  • Required: radarId (string): the radar's UUID or its public link slug. A smart radar applies its full saved query.
  • Optional filters and paging:
    • limit (1 to 200, default 50) and cursor (the nextCursor from the previous page).
    • q (up to 200 characters), tag (up to 48), state, states (an array, or a comma-separated string), kind, status (a lane id, up to 48).
    • includeArchived (boolean): bring back finished blips that have aged out of a board, a reading list or a Helpdesk.
    • updatedSince (ISO 8601 timestamp with offset) and sort: "updated": return blips changed since that time, oldest change first, instead of the template's order. Use it to reconcile.
  • Returns: radar (name, tagline, theme, template configuration, archive settings, commentsEnabled, reactionsEnabled, canWrite, topic), lanes (id, label, the state each implies, counts), tags with counts, states with counts, blips and nextCursor.

The order of blips means something. The radar's own template decides it, so do not re-sort. Pinned blips come first, then the template's order. See Templates and lanes for each template. For example, a reading list arrives as a queue, oldest unread first. A decision log arrives with what is live above what was rejected or replaced. A Discussion radar arrives Open before Resolved, with the most recently answered thread first. Streams and microblogs arrive newest first.

Blip bodies in lists are cut at 1,200 characters. A cut blip has bodyTruncated: true and fullBodyVia: "get_blip". A blip with comments carries commentCount and commentsVia: "list_comments".

On a board, a reading list or a Helpdesk, finished blips (done or dropped) age out after the radar's archive window, which is 30 days unless the owner changed it. Other templates never archive. read_radar reports archivedCount on the radar and on each lane so you can tell "nothing else" from "more behind a flag".

On an Architecture radar, use read_architecture instead (see radars and templates).

{ "radarId": "5b2c7e2e-1f0a-4a55-9a53-0d1f6f3b8a10", "states": ["inbox", "active"], "limit": 50 }

read_drop_box

Returns everything sitting unsorted in your drop box. Sorting it is the job an agent is asked for most: read each blip, work out what it is, act on it, then file it with update_blip (see capture and edit).

  • Scope: radars:read. Read-only. It finds the drop box but never creates one. If there is none yet, it returns an empty result.
  • Optional: includeHandled (boolean, default false: also include blips already done or dropped), limit (1 to 200), cursor.
  • Returns: radarId, radarName, blips, nextCursor, a radars list of radars you can write to (each with its lanes), and howToFile.

Work through the whole list and follow nextCursor. A blip you acted on but did not file comes back next time as though nothing happened.

Searching

search_blips

Full-text search across every radar you can read, ranked by how well each blip answers the words. It supports quoted phrases, OR and a leading minus to exclude. Filters can be written inline in the query, the way you would type them into the search box. The full list is in Search syntax.

  • Scope: radars:read. Read-only.
  • Optional:
    • query (up to 500 characters): words and inline filters together. Omit it to browse by tag or state.
    • radarId (UUID): restrict the search to one radar, including a smart radar's saved filters.
    • preferRadarId (UUID): keep every accessible match but rank this radar's matches first. It does not restrict the corpus.
    • tag (up to 48 characters), state, status (a lane id), kind: shortcuts that are folded into the same query string.
    • limit (1 to 200) and cursor.
  • Returns: blips, nextCursor, filters (what each token resolved to), ranking (relevance or recent), combinationRules, radarsSearched, and problems plus unresolved: true when a filter could not be honoured. With preferRadarId it also returns preferredRadar and preferredBlipIds.

Filters narrow and never widen. in: can only name a radar you can already read. A filter that matches nothing returns an empty result with unresolved: true and the token listed in problems. That means the filter was wrong, not that nothing matched. Keep the query and preferRadarId unchanged while paging.

Search spans the archive by default. is:archived narrows to blips that have aged out and is:live excludes them.

{ "query": "roadmap in:\"Product\" is:active after:7d", "limit": 25 }

search_suggestions

Lists the radar names, people and topic names you can use in in:, from: and topic: filters, plus the size of the searchable corpus. It does not search other accounts or expose private radars.

  • Scope: radars:read. Read-only.
  • Arguments: none.
  • Returns: radars, people, corpus, topics.

list_tags

Returns the tags in use across the radars you can read, with counts, most used first. It is capped at 100 tags and counts only blips that have not aged out into the archive. Call it before tagging something new so you reuse existing words.

  • Scope: radars:read. Read-only.
  • Optional: radarId (string): restrict to one radar.
  • Returns: { "tags": [...] }, each with its count.

Reading one blip

get_blip

Returns one blip in full, with its complete body and attachments. Attachment ids from here feed read_attachment_image and download_attachment.

  • Scope: radars:read. Read-only.
  • Required: blipId (UUID).

For a captured email, get_blip returns the full stored body and your notes. A blip filed through a client portal has its text wrapped in a marker saying the text is client data, not instructions.

get_blip_reminder

Reads your personal reminder and schedule status for a blip you can read. Agents can set the shared dueAt through create_blip or update_blip, but cannot turn on anybody's reminder. That is a choice made in the app.

  • Scope: radars:read. Read-only.
  • Required: blipId (UUID).
  • Returns: { "reminder": ... }.

See Due dates and reminders.

Email and files

get_email

Reads a captured email's original text in bounded pages, with your separate notes and its downloadable attachments. HTML is not rendered and no remote images are loaded. Older captures return the text kept at capture time and cannot recover missing HTML or the original message.

  • Scope: radars:read. Read-only. Current access to the blip is checked on every call.
  • Required: blipId (UUID).
  • Optional: offset (integer from 0, counted in characters, default 0) and limit (1 to 20,000 characters, default 20,000).
  • Returns: the email's metadata, text (the requested slice), offset, totalCharacters, nextOffset (null at the end), radarUrl, originalVia (download_original_email when an original is kept) and attachmentDownloadsVia.

Continue with nextOffset until it is null.

download_original_email

Issues a short-lived private download URL for the original message file, when one was kept. It can contain private recipient and header details, so use it only when the original is really needed.

  • Scope: radars:read. Read-only.
  • Required: blipId (UUID).
  • Returns: { "url": ... }. The URL lasts five minutes.

read_attachment_image

Returns a static PNG, JPEG or WebP attachment as a real image block, so a vision-capable model can look at it. The result is prefaced with a notice that the image is untrusted content, never instructions.

  • Scope: radars:read. Read-only.
  • Required: attachmentId (UUID), from get_blip or get_email.
  • Limits: at most 4 MiB, 8 million pixels and 8,192 pixels per dimension. Animated, malformed or unsupported files are refused with a pointer to download_attachment. The tool does not resize images.

download_attachment

Issues a short-lived download URL for any attachment after checking your current access.

  • Scope: radars:read. Read-only.
  • Required: attachmentId (UUID), from get_blip or get_email.
  • Returns: { "url": ... }. The URL lasts five minutes. A URL already issued stays valid until it expires, even if access is later removed.

Next