get-notifications

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

No annotations are provided, so the description carries the responsibility of disclosing behavioral traits. It states that notifications are 'recent' and scoped to the user ('your'), implying authentication and time-based ordering, but it does not explicitly state whether fetching notifications has side effects like marking them as read. Some behavioral details are left to inference.

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 a single sentence that immediately conveys the tool's function without any extraneous information. It is front-loaded with the verb 'Get' and the resource 'notifications.' This achieves maximum conciseness with no wasted words.

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?

The tool has no output schema and the description does not describe the return structure or format of notifications, which leaves some ambiguity about what the agent can expect. For a simple read operation with well-documented parameters, the description is adequate but not complete: it lacks details on ordering, pagination behavior, and read side effects. Given the absence of annotations, the description should provide more context.

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 provides comprehensive descriptions for both parameters (limit and filter) with defaults and constraints, covering 100% of the parameters. The description adds no extra meaning beyond the schema; it mentions notification types that already appear in the filter enum. The baseline of 3 is appropriate as the schema does the heavy lifting.

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 tool retrieves the user's recent Bluesky notifications and enumerates the included types (likes, reposts, follows, mentions, replies). This specific verb+resource structure distinguishes it from sibling tools like get-timeline-posts or get-feed-posts, which serve different purposes. The purpose is unambiguous.

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 implies the tool is used when a user wants to see their notifications, but it does not explicitly state when to choose it over alternatives such as get-timeline-posts or get-feed-posts. No exclusions or comparisons are provided. The usage context is inferred from the tool's purpose rather than explicitly guided.

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