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

With annotations covering the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false, idempotentHint=false), the description still adds non-obvious behavior: per-call quota cost that varies by operation type, where to find the exact figure, and that failures surface as a tool error with upAPI's error code rather than breaking the session. It does not address idempotency or auth, so it is strong but not exhaustive.

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?

It is front-loaded with the core action, followed by the prerequisite, cost, and error semantics, with no filler sentences. The quota sentence is somewhat dense but each clause carries distinct information, so it earns its length.

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 dispatcher tool with no output schema and a free-form nested `input` object, the description covers the important unknowns an agent faces: how to find valid slugs, that cost varies, and how failures are surfaced. It does not describe the shape of a successful result, though the open-world variant operations make that largely infeasible anyway.

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 100%, so the slug and input parameters are already fully documented in the schema (including the example slug format and the "omit for an operation that takes none" rule). The description reinforces the linkage to `search_ops` output but adds no syntax or format detail beyond the schema, which is the expected baseline.

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?

"Run one upAPI operation by slug" states a specific verb and resource, and it explicitly distinguishes itself from the sibling `search_ops`, which the agent needs to call first. An agent can tell what this tool is for 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?

It names the prerequisite explicitly: discover slugs and their parameters with `search_ops` first, so the agent knows the correct ordering across siblings. It stops short of stating when-not to use this tool (e.g., prefer a dedicated sibling like github_repo_get when one exists), so it is clear context rather than full routing guidance.

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