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

Annotations declare openWorldHint, idempotentHint=false, and destructiveHint=true, but the description adds no context on any of these. It does not say what repeated calls do (duplicate pull? dedupe?), that it depends on external store connections, or what happens to already-imported orders; the description says nothing that goes beyond what the annotations already cover.

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?

One front-loaded sentence with no filler; the source scope and destination are stated up front. It is efficient, but so terse that useful routing and behavior information was omitted rather than compressed.

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?

This is a mutating, non-idempotent tool that reaches out to external stores, and the description never explains the effect of repeated calls, whether the sync is asynchronous, or when to choose it over list_import_orders. With no output schema, an agent also gets no information about what the call returns. For a tool with this much behavioral weight, the definition is under-specified.

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 one parameter, wait_seconds, has a complete schema description including default, range, and the meaning of 0. Because schema coverage is 100%, the baseline of 3 applies, and the description adds nothing beyond the schema.

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 gives a specific verb and resource ('Pulls new orders'), names the source scope ('every connected store'), and names the destination ('Import list'). It is clear on its own, but it draws no boundary against siblings such as list_import_orders or list_store_connections, so an agent cannot tell from the text alone which one to reach for.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no mention of prerequisites such as having at least one connected store. The agent must infer usage from the single sentence, and the description never contrasts this tool with the other order-listing tools.

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