select_least_cost_capable_model

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description still adds real behavioral content: no side effects on the runtime, unresolved results for inadequate cost evidence, and an explicit warning that savings are not guaranteed. It does not define what 'declared cost rank' means precisely or how ties are broken.

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?

Purpose and selection rule are front-loaded in the first sentence, followed by the catalogue reference and then the side-effect/no-guarantee caveats. Every clause carries information; nothing is redundant padding.

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 covers the resolution policy and the absence of side effects. The main residual gap is the internal structure of the nested catalogue, which is delegated to an external GitHub link rather than spelled out.

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 the single parameter is a nested, open-ended object, so the description must carry the burden. It does name the two relevant top-level fields (required_capabilities and models) and points to an external spec, but leaves the per-model entry shape (cost rank, availability, authorisation fields) and the field naming/format entirely to the URL.

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?

States a specific verb (pick/select), the resource (a model from a supplied catalogue), and the exact selection criterion (lowest declared cost rank among capability-satisfying, available, authorised models). The sibling tools (lead-source ranking, telemarketing consent, GDPR reporting) are in unrelated domains, so no disambiguation is needed and none is expected.

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?

Makes the operating context clear: this is a pure selection/decision helper over a caller-supplied catalogue, and explicitly not an execution step ('Nothing is called, switched or launched'). It also gives the fallback rule for ambiguous input (unknown or non-comparable cost evidence stays unresolved), though it never states explicit prerequisites for the catalogue or a when-not-to-use case.

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