Nachricht flaggen

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

With no annotations provided, the description carries full burden and it delivers: it discloses mutation ('Verändert die Nachricht'), the ambiguity policy (multi-match → no change, report ambiguity), the flagIndex constraint (only applicable when flagged=true), and the color semantics. It does not mention auth requirements or reversibility beyond the unflag toggle, which keeps it slightly below 5.

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?

Well-structured single block that front-loads the core action, then covers edge cases and use case. Every sentence earns its place—no filler. Slightly verbose with the parenthetical color mapping and schema redundancy, but overall efficient.

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 mutation tool with no output schema and no annotations, the description covers the key behaviors: mutation, ambiguity handling, minimal parameter requirements, and a concrete use case. It could mention prerequisites (existing message) or what the return value signifies (success vs ambiguity), but the guidance is solid for selecting and invoking.

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 100%, so all 5 parameters are documented in the schema. The description adds minimal extra value: it maps flagIndex to actual color names and states the minimum requirement (subjKey or senderKey), which slightly enriches the schema. Baseline 3 is appropriate given full schema coverage.

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?

Specific verb+resource: 'Setzt oder entfernt die Fahne an GENAU EINER Nachricht' clearly states it flags/unflags exactly one message. It discloses the flag color range (0-6: rot, orange, gelb, grün, blau, lila, grau) and distinguishes itself from search_messages/siblings by focusing on mutation of a single matched message.

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?

Explicitly states the practical use case ('Praktisch, um eine verarbeitete Rechnung zu markieren'), describes the when-not behavior (if key matches multiple messages, nothing is changed and ambiguity is reported), and provides parameter guidance (mindestens subjKey oder senderKey angeben). This clearly differentiates from read-only siblings like search_messages and get_message_body.

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