Skip to main content
Glama

annotate_icons

Generate a numbered grid of an app's unlabeled icons with context from memory. Read the picture, decide what each control is, and submit answers via submit_icon_labels.

Instructions

Ask what the wordless icons of an app are called — the first half of a round trip that has to happen once per drawing, ever. Choto's memory is text: an icon with no label is a place it knows how to click but cannot name, and observe reports those as 'icons: K labeled, M unlabeled'. This tool returns ONE picture (occasionally a few) holding every unnamed glyph of one application as a numbered grid at its real pixel size, plus a text legend giving each cell its context from memory: the app, the window it sits in, roughly where in that window (toolbar strip, sidebar column, bottom-right...), its size, the nearest few texts beside it, and any other windows the same drawing appears in. Read the picture, decide what each numbered control is, and send the answers with submit_icon_labels — that is the whole loop: observe -> annotate_icons -> submit_icon_labels -> click the label like any other text. app_name is optional: without it the app with the most-drawn unnamed glyph is chosen and named in the reply, because a glyph means whatever the program drawing it says it means and one sheet therefore covers one app. Nothing is captured and nothing is clicked — the crops come from memory, so this is safe to call while the user is working. If every glyph already has a name the reply says so plainly; the sheet is capped, and the reply says how many are left for a second call.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
app_nameNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/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: crops come from memory, nothing is captured or clicked, it is safe to call while the user is working, the sheet is capped, and the reply reports remaining counts. It even explains why one sheet covers exactly one app.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence ('Ask what the wordless icons of an app are called...') is indirect framing rather than a direct statement of what is returned, so the key payload arrives late. The rationale sentence about glyphs meaning whatever the drawing program says adds color but is not strictly needed for correct invocation.

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?

No output schema or annotations exist, yet the description fully covers the return format (picture plus legend fields: app, window, position, size, nearby texts, other windows), edge cases, and the next step. An agent has everything needed to call and interpret it.

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 0% for the single app_name parameter, so the description must compensate, and it does: app_name is optional and, when omitted, the app with the most-drawn unnamed glyph is selected and named in the reply. It does not, however, specify accepted name formats or how matching is performed.

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 action and concrete return artifact: a numbered-grid picture of every unnamed glyph of one application plus a text legend with per-cell context. It also explicitly distinguishes itself from siblings observe and submit_icon_labels by naming them in the round trip.

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 explicit when-to-use (after observe reports 'icons: K labeled, M unlabeled'), the paired follow-up tool (submit_icon_labels), the sequencing loop, and the app_name-omitted behavior. It also states the terminal case (all glyphs named) and the cap with a hint to call again.

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