set_role_pinAssign a fixed provider and model to a role, ensuring sub-agents use that pairing when available. Falls back to dynamic routing if the pinned target becomes unusable.
Pin a role to a preferred (provider, model). Auto-route by pin on later sub-agent runs; falls back to dynamic when the pinned target is unusable.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | ||
| profile | No | ||
| model_id | Yes | ||
| provider | Yes |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that this is a persistent configuration change (pins a role), that it affects future sub-agent runs, and that it falls back to dynamic routing when the pinned target is unusable. Some behavioral details remain uncovered, such as whether this overwrites an existing pin or whether provider/model validity is checked, but the description is strong for a configuration 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 with no wasted words. The core action is front-loaded, and the behavioral note about fallback earns its place. Perfectly sized for what it communicates.
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 config-pinning tool with 4 params and no output schema, the description covers the main outcome and follow-on behavior. It could mention what happens if the pin already exists or how to view pins (list_role_pins), but these are minor gaps given the tool's simplicity.
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, but it provides limited detail about the parameters beyond their names. The term 'preferred (provider, model)' maps loosely to provider and model_id, and 'a role' maps to role, but profile is not mentioned at all. The enum for provider is left to the schema. The description adds some interpretive context but doesn't fully compensate for the lack of schema documentation.
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 uses a specific verb ('Pin') and identifies the resource ('a role to a preferred (provider, model)'). It clearly states the purpose and even distinguishes itself from dynamic routing behavior. It doesn't explicitly name sibling alternatives like list_role_pins or delete_role_pin, but the purpose is still clear enough.
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 explicitly states when this tool is used ('Pin a role') and what happens on later sub-agent runs ('Auto-route by pin'). It also explains the fallback behavior when the pinned target is unusable. This gives clear usage context without needing to reference sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.