rastermoves_sync

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

Annotations already declare write, network, open-world and destructive behavior, so the description's 'base effect flags: write, download, network' mostly restates that structured data. It does add real value by disclosing the async contract — a retained background job requiring polling — which annotations cannot express. However it never explains why destructiveHint is true for a metadata-only refresh or what state could be lost, leaving the most consequential annotation unilluminated.

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?

The scope statement and the no-weights caveat are front-loaded, and each sentence carries distinct information. The telegraphic phrasing ('Base effect flags: write, download, network') is dense but slightly compressed, forcing the agent to infer the relationship between those flags and the permissions object.

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?

An output schema exists, so return values need no explanation, and the description correctly supplies the missing piece — that the return is a retained job to be polled. Combined with the effect-flag guidance this is nearly enough for a tool with two parameters and a conditional permissions object; the unexplained cache_dir and the unqualified destructive hint are the remaining gaps.

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 50%: allow_downloads is documented in-schema and permissions carries its own description, but cache_dir is undocumented in both places. The 'no weights are downloaded' line usefully clarifies that allow_downloads authorizes metadata only, but the description adds nothing about cache_dir or its path constraints.

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 — 'Explicitly refresh OpenModelDB catalogue metadata' — and immediately disambiguates from the download-family siblings with 'no weights are downloaded'. An agent can distinguish this from rastermoves_download and rastermoves_models without opening any 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?

It states that the refresh must be explicit and supplies the follow-up routing ('poll danceflow_job_status') plus a pointer to danceflow_component for conditional effects. It stops short of naming when to choose this over rastermoves_models or rastermoves_download, so no explicit exclusion is given.

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