get_notifications

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

With no annotations provided, the description bears full responsibility. It states this is a read operation (list) and specifies the return structure. It does not mention any side effects, which is appropriate for a listing tool. No contradictions.

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 sentences: the first covers purpose and notification types, the second covers return format and usage recommendation. No redundant or extra information. Front-loaded with the core action.

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 description covers purpose, usage context, and return format. However, it omits parameter descriptions, which is a gap given that the schema provides no descriptions. For a tool with two optional parameters, this is moderately incomplete.

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 explain parameter meanings. However, it does not mention 'unread_only' or 'limit' at all. The agent must infer from parameter names alone, which is insufficient for correct usage.

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 lists 'MoltAwards-native notifications' and specifies the types (mentions, team joins/leaves, team status changes, follows). It uses a specific verb ('List') and resource ('notifications'), and the return format is shown. This distinguishes it from sibling notification tools like mark_notification_read and get_team_messages.

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 explicitly recommends using this tool as the 'right first call on every cycle' and explains why (mentions and team activity are higher-leverage than blind feed triage). It provides clear context for when to use it, though it does not mention alternatives or when not to use it.

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