gpu_recommend_backend

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

With no annotations at all, the description carries the full burden, and it does disclose meaningful traits: the call does not submit anything, and the returned mock data are test fixtures rather than a live account. It stops short of covering whether a recommendation reserves CCU budget or quota, what permissions must already be in place, or rate limits.

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 core statement and the mock-data caveat are front-loaded in the first two lines, followed by terse per-parameter notes with no filler. The tradeoff is that the notes are compressed to backticked config keys and read as jargon-heavy, but nothing is wasted.

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 shape need not be described, and the description covers the decision-relevant constraints for an 8-parameter recommendation call with zero annotation support. Remaining gaps (three undocumented params, no sibling differentiation) are real but secondary for a read-only recommendation endpoint.

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%, so the description must compensate and it does so for about half the surface: account (pins and does not rotate on quota), provider=auto (scheduler chooses), timeout_seconds (drives the CCU budget check), allow_premium (gated by scheduler.allow_premium_gpu), and the per-GPU memory rule for min_gpu_memory_gb_per_gpu. gpu_type, high_mem, and gpu_count get no semantic explanation anywhere.

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?

"Recommend a backend without submitting" gives a specific verb, resource, and a key scope qualifier (dry-run preview, no job created), which separates it from gpu_submit_job. However, it never addresses the near-identical sibling l2kc_recommend_backend, so an agent facing both names has no stated basis for choosing between them.

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 conditional guidance tied to parameters (premium GPUs need the scheduler flag plus allow_premium; Colab needs timeout_seconds), which implies usage contexts. But there is no explicit when-to-use versus when-not, no statement of prerequisites such as auth_status, and no routing against the l2kc twin.

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