Set Provider Preference Order

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It doesn't state that this operation persists globally, whether it overrides existing order, if it affects ongoing routing immediately, or any side effects on other providers. 'Global' hints at scope but not consequences; an agent cannot anticipate what happens to current routing until after invocation.

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 description is a single, compact sentence that states the core action and scope. It is appropriately short for a simple one-parameter tool. However, it could be slightly more informative without being verbose, e.g., by mentioning 'order values must be from the supported provider list' or 'affects routing globally', but the structural efficiency is good.

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?

Given the tool has one parameter and no output schema, the description should suffice for straightforward invocation, but it lacks critical context: what the order array represents (priority ranking), the effect on routing, and any constraints (e.g., must include all providers or at least one). The sibling context shows many configuration tools, but this description doesn't explain how this order interacts with other settings like enabled providers. An agent might not know if setting an order alone is sufficient or if additional steps are needed.

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 0% and there are no enum annotations on the parameter, though the schema defines an array of strings with an enum list in the items. The description does not explain what values should be in the order, the expected order of preference (e.g., first is most preferred?), or whether all providers must be listed or a subset is allowed. The agent must read the schema and infer semantics from the enum names, so the description adds no meaning beyond what the schema provides.

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 states a clear verb ('Set') and resource ('global provider preference order'), and it distinguishes from siblings by indicating it sets the global order (not per-provider or per-key operations). However, it doesn't specify what 'provider preference order' means practically or how it affects routing, leaving some ambiguity for an agent; it's clear enough to be a minimal viable purpose but not distinct enough to avoid confusion with configuration tools like nanites_setProviderEnabled.

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 guidance on when to use this tool versus alternatives. With many nanites_* configuration tools in the siblings, an agent could confuse this with setting provider keys or enabling/disabling providers. No context is given on the typical use case (e.g., during initial setup or to change routing priorities), so the agent must infer usage from the name alone.

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