Ta bort stjärnmärkning

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

The description goes well beyond the annotations: it explains the direct IMAP flag removal versus the Bridge Starred view only refreshing every 20-40 seconds, that the mail stays in its folder and is never deleted, the partial-failure case where the star is removed but the mail may linger in Starred for up to a minute, and the exact rejection conditions (UID not in mailbox, Bridge denial). This is consistent with destructiveHint=false and idempotentHint=true while adding information the annotations cannot carry.

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?

Front-loaded with the action, then structured into behavior, Args and Returns sections, so it is easy to scan. It is on the long side and the uid list behavior is restated in both the Args block and the schema, a minor redundancy, but every paragraph carries operational detail.

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 two-parameter mutation tool with a sync-timing quirk, this covers everything an agent needs: preconditions, per-mailbox UID scoping, batch limits, partial-failure semantics and rejection behavior. It even restates return shapes despite an output schema existing, which is redundant but not harmful.

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 only 50% (mailbox has no schema description), and the description fully compensates: it states mailbox is obligatory and why UIDs are scoped per folder, where to obtain the mailbox value, that up to 100 UIDs from the same mailbox are accepted, and that an invalid UID or more than 100 rejects the whole call before any change. This adds genuine semantics beyond the schema's anyOf constraint.

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 opening sentence names a specific verb and resource ('Ta bort stjärnmärkningen från ett mejl') and immediately grounds it in the IMAP \Flagged flag, so the operation is unambiguous. It never explicitly names the inverse sibling flag_email, so the agent must infer the pairing from the name, but the action itself is precise.

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 gives real contextual guidance: UIDs are per-mailbox, the mailbox value should be taken from the response of list_emails, search_emails or get_email, and 'Är det inte stjärnmärkt händer inget' sets expectations for the no-op case. It stops short of explicitly stating when to choose this over flag_email or other label tools, so the alternative-selection guidance is implied rather than stated.

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