sync_league

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

With no annotations, the description carries the full behavioral disclosure burden for this slow, rate-limited operation. It discloses the approximate per-request cost, the expensive first-run behavior, and CDN rate limits. This is unusually candid and valuable context for an agent deciding when to call the tool.

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 sentences deliver the core action, critical performance caveats, and a usage cadence. The most important operational warnings are front-loaded, and every clause earns its place.

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 simple tool with one optional parameter late dated and no output schema, the description covers timing and cost well. However, it omits the semantics of force and does not point to sync_recent as a lighter-weight alternative, leaving a notable gap in what an agent needs to make the best call.

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 schema defines one parameter, force, with no description coverage. The tool description never explains what force does or when to set it to true. Since schema coverage is 0%, the description needed to compensate but did not address the parameter at all.

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 and resource: 'Refresh the local cache from the BBF site.' This is specific and immediately signals the tool's function. It does not explicitly differentiate itself from sync_recent, a sibling that likely has a similar refresh purpose.

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?

The description gives explicit cadence guidance: 'run it weekly, not before each query.' This tells the agent when to invoke the tool and when not to. It does not name an alternative like sync_recent, so it falls short of full alternative routing.

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