unread_messages

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

No annotations are provided, so the description carries the full burden. It discloses a critical limitation: the local Teams cache has NO general read marker, so true 'all unread' can't be derived. This is genuinely valuable behavioral information that prevents the agent from incorrectly interpreting results. It could add return-format details, but the core limitation disclosure is strong.

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 front-loaded with the core purpose statement and then adds a well-structured limitation warning with a clear alternative. It's moderately long due to the credential caveat, but every sentence earns its place — the limitation warning is essential and the alternative routing prevents misuse. Slightly verbose in formatting but efficient in content.

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 is conceptually complex (subject to cache limitations, needs disambiguation from 'all unread' assumptions and from the recently-arrived interpretation). An output schema exists but its structure is not examined here. The description adequately covers the key semantic trap (per-message read state not stored on disk) and the routing decision. Given the complexity of what could go wrong, this is well-covered.

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 carries all parameter burden. However, the description does not explain any of the three parameters (days, limit, account). 'days' semantics can be inferred from the recent_messages contrast, but limit and account are entirely undocumented. Mean-while, the parameter names are relatively self-explanatory, so a baseline 3 is appropriate.

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 what the tool returns: 'unread @-mentions'. The verb 'unread items needing attention' combined with the explicit mention of @-mentions gives a clear purpose. It distinguishes from sibling tools by contrasting with recent_messages, though it ties the purpose to the limitation explanation rather than stating it crisply up front.

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?

This is exemplary. The description explicitly explains when NOT to use this tool and names the exact alternative: 'For everything that arrived while I was away, use recent_messages(days=...) instead'. It even explains the reasoning (you read nothing while away → recent ≈ unread). This is the highest quality usage guidance possible.

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