get_recent_notifications

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

Annotations already establish this as a read-only, non-open-world operation. The description adds valuable behavioral context: the result is capped at 30 records, it is only a recent window, notification text is untrusted, and dismissal is a separate action.

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 sentences, front-loaded with the core operation and then adding the safety warning and scope limitation. Every sentence contributes useful information without repetition.

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 read-only tool with annotation safety coverage, the description supplies the key scope, cap, filter mention, and untrusted-data warning. It remains slightly incomplete on source/status value semantics, but no output schema is present to require return-value explanation.

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 parameter meaning. It mentions all three parameters indirectly and adds the important cap of 30 for limit, but it does not define valid source or status values, nor does it explain filtering semantics beyond naming the fields.

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: read recent inbox records, with an explicit 30-record cap and optional source/status filtering. It also distinguishes the tool from dismissal operations by stating that dismissing is separate.

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 frames the tool as a recent window and explicitly warns that it is not a complete historical audit. It also names the boundary with dismissal, though it does not name a specific alternative tool for full-history retrieval.

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