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

Annotations declare idempotency and non-destructiveness, but the description goes further: it states re-marking does NOT reset the first-read timestamp, there is no unmark, and the response includes the new unread_count. The tier restriction ('sp500+') is also disclosed, adding behavioral and access context 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?

Three concise sentences pack the essential information with no filler. The action is front-loaded, and each subsequent sentence adds critical usage details (id source, idempotency, unmark absence, return value, tier restriction).

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 a single fully-described parameter, an output schema, and annotations, the description covers all important aspects: correct id source, side effects, no-unmark guarantee, return value, and access tier. It is complete for an agent to select and invoke the tool correctly without needing further documentation.

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 input schema fully describes inbox_id with its source. The description adds valuable disambiguation by explicitly stating 'not a signal id' and reinforces that inbox_id comes from list_signal_inbox or the signals feed resource, which prevents id-type confusion. Although schema coverage is high, this extra clarification justifies above-baseline scoring.

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 the action ('Set read_at on a single inbox item by its id') and distinguishes the resource from a signal id, explicitly noting the id source. It also differentiates from sibling tools like dismiss_inbox_item by describing the specific read_at mutation.

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 provides clear usage context: it applies to inbox items from list_signal_inbox or the signals feed resource, and explicitly warns 'not a signal id'. It also clarifies idempotency and that there is no unmark, giving the agent important constraints. However, it does not explicitly name alternative tools or an when-not-to-use scenario, so it falls one short of full guidance.

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