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

Annotations already declare non-destructive and non-read-only, and the description adds substantial context beyond them: host-only restriction, archiving rather than deletion, timing (after the turn ends and the user leaves the app), incident status handoff to `track`, and reversal via a new send. That is exactly the behavioral disclosure expected of a mutation tool.

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

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

The core semantics are front-loaded in the first two sentences and the framing 'never deleted' is well placed. The trailing 'Args:' block adds little for a one-parameter tool and slightly dilutes the concision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 need not be described, and the description covers scope, side effects, and reversal. The only material omission is what form the `topic` argument takes.

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

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

Schema coverage is 0% and the description only restates the parameter as 'the topic to close', giving no hint about whether it is an ID, slug, or name. The role of the single parameter is obvious, so this is adequate but does not compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Close a topic') plus its concrete effect (conversations archived, never deleted). An agent can distinguish it from neighbors like `track` and `send` 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the default behavior absent the call ('a topic conversation is archived after 12 h without messages'), which is a clear use case, and notes that incidents are handled by `track` instead. No explicit when-not guidance beyond that, but the implied context is strong.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real value beyond them: results are previews, not full bodies, and the result set deliberately omits messages another session is awaiting. That is exactly the kind of set-composition detail an agent cannot infer.

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

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

Two compact sentences, front-loaded with what the agent gets, followed by the two exclusions that would otherwise cause misreads. No filler or restatement of the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape need not be described, and the description covers the non-obvious filtering rules. What's missing is a note on bounding or truncation of the preview list, a minor gap for a zero-parameter listing tool.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The mention of `read(id)` clarifies the sibling's signature rather than this one's, which is still useful context but adds nothing to this tool's own parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names the resource (unread messages) and its scope (preview only) with a clear, agent-usable framing. It also differentiates from the sibling `read`, so the agent can pick between the two without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to `read(id)` for full content and notes that replies pending in `wait_reply` are excluded, which prevents a wrong expectation. It stops short of stating a triggering condition (e.g., poll this first, then read), but the alternatives are named.

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

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

Annotations declare a non-read-only, non-idempotent, closed-world write. The description adds genuinely useful context beyond that: the update is not final, it doesn't wake the sender, and it surfaces to the sender through track/wait_reply. It stops short of clarifying rate/latency behavior but covers the key side-effect semantics.

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

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

The behavioral guidance is front-loaded, the when-to-use line follows, and the two args are listed tersely with the one constraint that matters. No sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return-value detail is unnecessary, and the description supplies purpose, timing, visibility, and both parameter meanings. Only the exact 'request id' source and any delivery latency are left implicit, which is minor for a 2-param progress ping.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: id is 'request id' and note is 'where you stand, in one sentence (500 characters max),' supplying both meaning and a format constraint absent from the schema. The id mapping is thin, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description frames a specific action: reporting interim progress on a request addressed to the agent, explicitly 'not final.' It distinguishes this from the final answer via reply, giving an agent enough to tell it apart from siblings like reply and track, though the generic tool name 'progress' does some of the work of obfuscation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit timing ('at the start of a long task, then now and then') and an explicit exclusion ('the final answer always goes through reply'), plus the visibility relationship to track/wait_reply. That is when-to-use, when-not, and the alternative all in one place.

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

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

Given readOnlyHint=false and idempotentHint=false, the key disclosure is exactly what the description provides: the message is marked read if addressed to you, explaining the non-read-only, non-idempotent behavior. It also explains that attachments resolve to local paths and that images are returned after the text, which is genuine value beyond the annotations; it stops short of saying whether marking read is reversible or visible to the sender.

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

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

The behavioral sentence is front-loaded and the whole thing is short. The Args block repeating "message id" for a single required string param is mild redundancy but harmless.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 spelled out, yet the description helpfully previews attachment handling. Combined with the side-effect disclosure, an agent has what it needs to invoke it; only the source of the id and the visibility of the read-mark remain unstated.

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

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

Schema description coverage is 0% and the only parameter is documented solely as "id: message id," which mostly restates the property name. It does clarify that the id refers to a message rather than a thread, but adds no format or provenance guidance (e.g., where to obtain the id).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Read a message in full") and even names the side effect (marked read when addressed to you). It is distinguishable from list-oriented siblings like inbox, search, and summary, though it never names those alternatives explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: you need a message id, which suggests reading a specific message found via inbox or search. There is no explicit statement of when to prefer this over inbox/search, nor any precondition about which messages are readable.

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

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

Annotations already state readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope detail that omitting id releases all of the caller's reservations, but it does not explain side effects, permissions, or whether released reservations become available to others.

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

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

The description is short and front-loads the core action. The optional-all behavior is mentioned twice, which is slightly redundant but not harmful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter mutation with an output schema, the description provides enough to call the tool correctly. Missing permission/auth details are minor, and return values are covered by the output schema.

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

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

Schema description coverage is 0%, so the description carries the burden for the sole parameter. It explains that 'id' identifies a reservation and that the parameter is optional, in which case all of the caller's reservations are released, which meaningfully supplements the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Release') and resource ('reservations'), and clarifies that it can release either one reservation by id or all of the caller's reservations. It distinguishes the two behaviors clearly, though it does not explicitly name the sibling tool 'reserve' or compare against it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context: provide an id to release one reservation, or omit the id to release all of yours. It does not list exclusions or alternatives, but the operational choice is unambiguous.

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

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

Annotations only declare the generic safety profile; the description adds real behavioral effects: the original is marked read, the sender is woken, info suppresses waking, state distinguishes done/refused/failed, and files are copied into the room. It doesn't cover error/retry or permission behavior, but it discloses far more than the annotations do.

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

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

Purpose and the progress alternative are front-loaded, then a compact Args list; every line carries meaning. Slightly dense but no wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter mutation tool with no schema descriptions, the description covers purpose, side effects, the state/vote semantics and the key alternative; an output schema exists so return values needn't be explained. Only minor gaps (permissions, error conditions) remain.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning — and it does, explaining all six params: id, text (including the reason for refused/failed), info's non-waking semantics, vote values, state outcomes with default, and files being copied into the room. This goes well beyond the bare schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (answer) and resource (a message addressed to you) plus the topic scoping, and explicitly names the sibling 'progress' as the alternative when you are still working. It does not differentiate from other close cousins like 'send', 'close' or 'wait_reply', so sibling routing is only partial.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear when-to-use rule ('A reply closes the request: to say you are still working on it, use progress') and explains the info flag's purpose ('final agreement, closing note'). It does not say when a reply is inappropriate versus send/close, but the key routing decision is covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the scope 'all three agents' and the fields returned (who, what, why, until when), but does not cover permissions or response format (an output schema exists). There is no contradiction.

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

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

A single compact sentence fragment, front-loaded with the key noun and scope. Every word contributes to conveying what the tool returns.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters, complete annotations, and an output schema, the description gives enough information to invoke the tool correctly. It could better distinguish itself from reserve/release, but the core context is present.

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

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

The tool takes zero parameters, and schema coverage is 100%. There are no parameter semantics to describe, so the baseline score of 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States that it returns current file reservations for all three agents, including who, what, why, and until when. This is a specific resource and scope, though it does not explicitly differentiate itself from sibling tools like reserve or release.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus reserve, release, or other siblings. The intended usage is only implied by the phrase 'current file reservations'.

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

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

Goes well beyond the annotations: it discloses the mutual-exclusion guarantee, that a conflicting request is refused with who/why/until-when, that re-asking extends the TTL, and how exclusivity changes blocking behavior. These are exactly the concurrency semantics an agent needs and none are in the structured fields.

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

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

Front-loaded with the imperative and consequence, then a compact Args block with no filler. Slightly long in the refusal parenthetical but every clause conveys behavior, so it is close to optimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 need not be explained. With annotations covering safety and the description covering timing, refusal, extension, and all four parameters, nothing needed to call this correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: ABSOLUTE paths with folders-and-patterns semantics, reason as one sentence, ttl_min range 1–1440 plus extension behavior, and exclusive's False=shared meaning. Every parameter gains meaning beyond the bare schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (reserve) and resource (files), plus the scope of the reservation (files, folders' contents, patterns). It is clearly distinct from siblings like release, reservations, and read, which an agent can tell apart without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Reserve files BEFORE editing them" gives an explicit timing/context for use, which is the critical when-to-use signal. It does not explicitly name the alternative (e.g., call release to free a reservation) or any when-not condition, so it falls short of a 5.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description still adds real behavioral detail: accent- and case-insensitive matching, all-words-must-match semantics, quoted exact-phrase behavior, relevance-then-recency ordering, and the fact that nothing gets marked read. That is exactly the kind of match/ordering contract an agent cannot get from the annotations.

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

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

The behavioral contract comes first in two tight sentences, followed by a compact Args list with no filler. Every line carries either matching semantics or parameter constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 need not be described; combined with the documented parameters and match/ordering semantics, an agent has everything needed to call this correctly on the first try.

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

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

Schema description coverage is 0%, so the description must carry the load and it does: query accepts words or a quoted phrase, topic/sender are optional single-value limiters, sender's permitted values are enumerated, and limit is bounded to 1-100 with a default visible in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search the whole room history') plus the matching semantics, which instantly separates it from passive readers like inbox/read. The scope word 'whole' and 'nothing is marked read' make clear it is a non-mutating cross-history lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The filtering options (topic, sender) imply how to narrow a search, but the description never says when to prefer this over siblings such as inbox, read, or summary, nor when not to use it. Usage is inferable rather than stated.

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

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

Annotations declare non-read-only, non-idempotent, non-destructive, and the description is consistent: it discloses that the full path actually sends a real test message to a peer agent and blocks waiting for a correlated reply, with an explicit wait window (60-600 s). That is meaningful behavior beyond the annotations. It stops short of saying whether the test message persists in the recipient's inbox or what happens on timeout, which keeps it from a 5.

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

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

The behavior is stated first and the argument notes follow, with essentially no filler. The closing sentence about returning 'the table of both directions' is partly redundant given an output schema exists, and the landmark phrasing is jargon-heavy, but the whole thing is short and earns most of its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with an output schema, the description covers what it does, both modes, both parameters, and the wait bound. The remaining gap is operational: no statement of prerequisites (are the peer agents required to be running?) or what failure/timeout looks like, which matters for a tool that can block for up to ten minutes.

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

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

Schema description coverage is 0%, so the description must carry the load, and it largely does: `to` is documented with its two valid values ('codex' or 'antigravity') plus the omitted-means-landmarks-only semantics, and `timeout_s` is documented as the maximum wait with its 60-600 s range. It omits the default value (420) that the schema supplies and does not say what an invalid recipient does.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb-and-resource picture: it checks interface landmarks of Codex/Antigravity and, optionally, performs a real end-to-end wake (send test message, wake, read, correlated reply). This is clearly a diagnostic/self-test tool rather than any of the messaging siblings (send, reply, wait_reply). It does not explicitly contrast itself with nearby diagnostic siblings like status, where, or survey, which keeps it at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The two operating modes are spelled out cleanly: 'with `to`, a real end-to-end wake' versus 'omitted = landmarks only', which tells an agent exactly which mode a given call will trigger. What is missing is any statement of when to prefer this over siblings such as status or where, or a warning about the cost of the full path.

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

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

Annotations say non-read-only, non-idempotent, non-destructive, but the description adds the substantive behavior: the recipient is woken, info=True suppresses the wake, files are copied into the room when sent, review answers are bounced back once if the peer omits file:line and severity, and due_min creates a 'late' report. This is exactly the context annotations cannot carry.

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

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

Purpose and return value are front-loaded in the first sentence, then per-argument notes. Mostly dense and useful, though a few parentheticals (the French 'relis'/'relecture' inference aliases, the chatgpt/agy glosses) are terser than they need to be for a reader with no project context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a seven-parameter tool with an output schema, the description covers every argument and the key side effects. The gap is that topic is optional with a null default and the description never says what happens when it is omitted, nor what errors or rejection look like when a peer fails the review round-trip.

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

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

Schema description coverage is 0% and none of the seven parameters carry titles beyond bare names, so the description carries the full burden and does: it enumerates the valid 'to' values (claude, antigravity/agy, codex/chatgpt) that are absent from the schema, specifies the topic slug rules and the one-topic-per-project convention, and explains the semantics of info, due_min, files, and review.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Post a message for another agent in the TOPIC's room') plus the side effect ('the recipient is woken automatically') and the return value ('Returns its id (for wait_reply)'). This clearly distinguishes it from siblings like reply, inbox, and read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete selection guidance for flags: info=True means nobody is woken, review requests a file:line/severity answer, due_min triggers late tracking. It never explicitly contrasts send with the sibling reply tool, so an agent must infer when to answer an existing message versus start a new one.

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

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

Annotations already establish that this is a safe, read-only, idempotent operation with no external side effects. The description adds useful behavioral context beyond the annotations: reading quotas happens 'off the server loop' and can take about 15 seconds, which helps an agent anticipate latency.

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

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

Two compact sentences are front-loaded with the returned state fields and end with the important latency caveat. No sentence is wasted, and the structure matches the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters, an output schema, and rich annotations, the description is nearly complete for correct invocation. The listed state contents and quota-latency warning cover the main operational concerns, though it still omits sibling-relative guidance.

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

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

The tool has zero parameters, so there is nothing for the description to clarify. The baseline for no-parameter tools is 4, and no parameter-related gaps exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and enumerates its contents: unread messages, last wake, bell threads, Codex port, Antigravity sidecar, and quotas. It is clear what the tool returns, but it never distinguishes status from siblings like survey, summary, or where, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies a status-check use case but gives no explicit when-to-use guidance or exclusions. It does not say when to prefer survey, summary, where, or inbox, nor does it explain whether it should be called before or after those tools.

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

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

The annotations already declare the safety profile: read-only, idempotent, non-destructive, and closed-world. The description adds useful content about what the summary returns and that `read` is for deeper detail, but it does not disclose additional behavioral traits such as auth requirements, rate limits, or cost.

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

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

The description is front-loaded with the purpose and contents of the summary, and the `read(id)` pointer is useful. The `Args` block duplicates the schema somewhat and the long content list could be tighter, but there is little wasted information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple one-parameter interface, existing output schema, and rich annotations, the description is largely complete: it explains what the summary contains and when to use `read` instead. The main gap is that it does not specify the accepted format or identity of the `topic` parameter.

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

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

There is one required parameter with 0% schema description coverage. The description only says `topic: the topic to summarize`, which mostly restates the parameter name and does not clarify whether the value is a topic ID, name, or other identifier.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool summarizes a topic and enumerates exactly what the summary contains: participants, message count, closed status, unanswered/answered requests, outcomes, votes, and latest messages. It also distinguishes the tool from the sibling `read` by saying to use `read(id)` for details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context: use this to get an overview without reading everything, and use `read(id)` for details. It does not explicitly cover when to choose other siblings like `search` or `inbox`, but the main alternative is named.

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

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

The description adds substantial behavior beyond annotations: it opens, reads, and closes pages/menus with Escape, performs no action, is refused while the user is in the app, and restores the view. It also states that the result includes a summary and a diff with missing landmarks flagged. This is exactly the kind of side-effect and safety context an agent needs for a UI-navigation tool.

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

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

The purpose and key constraints are front-loaded and the description is not bloated. However, the parenthetical phrasing and the "Args:" formatting are a bit awkward, and "now" plus "never an action" add slight ambiguity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description need not fully document return shape, but it still explains the summary/diff result and missing-landmark flag. It covers the critical invocation constraints for a one-parameter UI-mapping tool: allowed app values, automatic alternative, refusal condition, side effects, and view restoration.

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

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

Schema description coverage is 0% and the schema has no enum for the single required app parameter. The description compensates fully by specifying the accepted values: "codex" or "antigravity".

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: mapping the Codex or Antigravity interface by opening/reading/closing pages and menus. It is specific enough for an agent to understand the operation, but it does not distinguish itself from any sibling tool by name or explain why one would use this rather than nearby tools like track or where.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives useful usage context: run it now, otherwise it happens automatically when the app version changes, and it is refused while the user is in the app. That covers a key when-to-use and when-not-to-use condition, though it does not explicitly compare against sibling tools or describe prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety/complexity profile is covered. The description adds the set of tracked lifecycle events, which is real behavioral context. It omits whether the call is a point-in-time snapshot or a long-running observation, and whether a message that was never delivered yields an error or an empty trace.

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

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

One compact sentence followed by a short Args line; nothing is padded and the core meaning arrives first. The Args block restates the single parameter in a formulaic way, but it is not wasteful enough to penalize heavily.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and annotations cover the safety profile, so return values and risk need not be spelled out. What is missing is the operational contract: one-shot vs blocking behavior, and the absence of any routing against the many similarly named siblings. Adequate but with a clear gap for a tool named as generically as 'track'.

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

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

Schema description coverage is 0%, and the only schema property is a bare string named 'id'. The description compensates by clarifying it is a 'message id', which is genuinely useful given siblings that might take other ids. It does not say where such an id comes from (presumably returned by send) or whether it accepts other id forms.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb (follow/track) and resource (a message), then enumerates the lifecycle stages covered: posted, delivered, wake attempts, read, answered. An agent can tell this is a per-message state tracker. It does not, however, distinguish itself from lookalike siblings such as status, progress, or wait_reply, and the parenthetical codenames (Antigravity, Codex) are internal jargon that adds no clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No statement of when to use this instead of wait_reply, read, status, or progress — all of which sound adjacent. There is no guidance on whether track is a one-shot snapshot or something that blocks/polls, which is precisely the decision an agent needs to make between this and wait_reply.

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

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

The annotations indicate a non-read-only, non-idempotent, non-destructive operation, and the description adds substantial context: the answer is marked read, reserved exclusively for the caller, invisible to other sessions' inboxes, and late replies are attached to the next call. It also covers the "restarting" relay state and timeout behavior, which are valuable operational details beyond the annotations.

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

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

The description is front-loaded with the core action and reservation semantics, then adds necessary edge-case behavior and parameter details without filler. Every sentence contributes operationally useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return structure need not be fully documented, yet the description still explains return semantics around missing answers and late_replies. Combined with the timeout and restarting edge cases, it gives the agent enough to invoke and interpret the tool correctly.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining that id comes from send and that timeout_s is a maximum wait in seconds ranging from 1 to 600 with a default of 300. Both parameters gain clear meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: wait for the answer to a message you sent, then return it. It also clarifies the reservation behavior while waiting, which distinguishes it from sibling tools like inbox or read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly says to use the id returned by send, and explains what to do when status is "restarting" by calling again. It does not explicitly compare this tool against alternatives such as inbox or read, so it falls short of a full when/when-not routing guide.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description remains consistent while adding real context: results come from the "latest map of its interface" and no live navigation occurs, so the agent knows the answer may be a snapshot. It stops short of saying what happens on a miss or how stale the map can be.

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

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

The core behavior and the no-navigation caveat are front-loaded, and the Args block is tight and example-driven. Dense jargon ("relay landmark", "debugging port") costs a little readability but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape needn't be spelled out, and the description nonetheless previews the returned fields. For a 2-param read-only lookup this is nearly sufficient; only failure/not-found behavior is left unaddressed.

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

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

Schema coverage is 0% (only bare titles "App" and "What"), so the description carries the burden and does it well: it constrains app to "codex" or "antigravity" and lists the accepted identifier forms for what (label, aria-label, data-* attribute, translation key, landmark name) with concrete examples. Minor gap: no statement of matching precedence or case sensitivity when multiple forms could match.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (a button/menu's location in Codex or Antigravity) and enumerates exactly what is returned: path, landmark, stable attributes, gestures. An agent can tell this is a UI-element lookup tool distinct from action siblings like send/close/read. It doesn't name a sibling to contrast with, which keeps it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"No navigation: only the stored map is read" sets a boundary on what the tool will do, which implies the usage context, but it never states when to prefer this tool over e.g. survey or status, nor any prerequisites. Usage is inferred rather than directed.

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