refresh

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

Annotations already flag a non-read-only, non-idempotent, open-world mutation, and the description adds genuinely new behavior: a bounded 20s wait, a possible 'still running' outcome, and the downstream reindex effect. It does not say whether a repeat call restarts or resumes work, nor what happens to data mid-reindex, which keeps it below a 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?

Two tight sentences with zero filler; the scope ('every folder... all accounts') is front-loaded before the timing caveat, which is where the agent needs it for a long-running call.

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 burden of describing the outcome, and it does so for the main branch (running vs. done). It leaves the completion response shape and the effect of the reindex on existing indexes underspecified, which is a small remaining gap given the annotations already cover safety.

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?

The single parameter is fully documented in the schema, including the omit-to-sync-all default and the reference to 'folders and status report' naming. The description's blanket 'one account or all accounts' only restates that, so the baseline of 3 for high coverage 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 specific verb+resource ('Sync every folder of one account or all accounts now, then reindex'), covering both the sync and the reindex step. That is concrete enough to separate it from sibling read tools like status, search, and folders without opening the schema.

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?

Gives a clear operating context: it waits up to 20 seconds, and if the pass is still running the agent may either call again or search the indexed data. That is actionable guidance, but it never explicitly contrasts the tool with the 'status' sibling for checking progress, so the routing 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.