m365_teams_messages

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses real behavioral caveats: bodies are capped at 2,000 characters, may contain incomplete HTML, and are not guaranteed to be the full history. It also states ordering (newest first), which annotations cannot convey.

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 tight sentences, front-loaded with what it does, followed by caveats, then the sibling routing. No sentence is redundant or restates the schema.

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?

With no output schema, the description carries the return-shape burden and does so: sender, timestamp, content type, and explicit truncation/incompleteness limits on the body. An agent has everything needed to call it and to set expectations about the result.

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 coverage is 100%, so both chatId and top are already documented, including the important note that top is a total cap across internal pages rather than page size. The description adds only the 'newest first' ordering and does not restate or enrich the pagination semantics, so 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 a precise verb and resource ('Read messages from one Teams chat') plus scope ('newest first') and return fields ('sender, timestamp and content type'). This clearly separates it from m365_teams_chats (which yields the chatId) and m365_teams_send (which writes).

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 explicitly routes the agent: 'Get chatId from m365_teams_chats' establishes the prerequisite, and 'Use m365_teams_send to post a message' names the write-side alternative. It stops short of stating when not to use it (e.g., that it reads a single chat rather than listing all chats), so it is clear context rather than full when/when-not guidance.

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