pbi_select_model

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

Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) cover the safety profile, and the description adds genuine context: it's a stateful selection ('para futuras operaciones') and discloses the exact pass-through contract ('TAL CUAL lo devuelve pbi_list_desktop_models') along with the anti-pattern it prevents (hand-extracting the port). No contradiction with annotations — re-selecting is indeed idempotent.

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?

Three tight sentences, each earning its place: purpose, when-to-skip-args, and how-to-pass-values. The bolded 'o' and inline format example aid scanning. Dense but efficient — zero filler.

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 stateful selection tool with an output schema present, the description covers the core flows: single model, multiple models, and the value-passing contract. Minor gaps: no comment on error behavior when no models are open or on whether selection persists, and catalog remains undefined. Still, given the output schema handles return values, this is largely complete.

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. It richly does for two parameters: port and connection_string are explained as interchangeable alternatives with a concrete format example and 'don't transform the value' instruction. However, the `catalog` parameter is never mentioned, leaving one third of the API surface undocumented in both schema and description.

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?

Uses a specific verb with resource and scope: 'Selecciona el modelo local activo para futuras operaciones' (selects the active local model for future operations). This crisply distinguishes it from ~140 siblings like pbi_list_desktop_models (listing), pbi_define_port_contract, and pbi_test_connection. The purpose is unmistakable even without reading further.

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?

Excellent when/when-not guidance: single open model → no args needed; multiple models → pass `port` or `connection_string`. It explicitly references the companion tool pbi_list_desktop_models as the source of values and explains the pass-through contract so the agent doesn't transform input. Loses a point on not explicitly naming sibling alternatives to rule out, and doesn't state what happens when called with no args if multiple models are open.

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