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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds a genuinely useful behavioral fact not in structured data: 'Orbit never notifies you about your own actions, so nothing here was written by you,' which tells the agent the result set excludes self-authored events. Pagination semantics are left entirely to the schema.

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 short sentences, front-loaded with the resource and the use case, with the exclusion rule last. No filler, though the 'your inbox' framing plus the explicit 'designed to be fetched' phrasing is slightly redundant with the name and title.

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 zero-required-parameter list tool with full schema coverage and read-only annotations, the description supplies the missing piece: what the feed contains and why the agent should use it. Only return shape and pagination behavior are unaddressed, which is minor given the cursor param in the schema and no 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 100%, so all four parameters (type, limit, cursor, unreadOnly) are documented at the source. The description's list of event categories loosely parallels the type enum but adds no new syntax or filtering detail, so the baseline 3 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 the resource (notifications inbox) and enumerates the concrete event families it contains: mentions, assignments, replies, state changes. It clearly differentiates itself from the inbox-conversation siblings by being the personal notification feed, though it never names an alternative tool 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?

Gives a clear situational trigger: 'This is how you find work someone has handed you by name.' That tells an agent when this tool is the right choice, but it offers no when-not guidance and does not route to siblings like list_my_issues or list_inbox_conversations.

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