prepare_blame

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

With no annotations, the description carries the behavioral burden. It discloses that the tool returns only device metadata and points to another resource for the annotated config, but it does not clarify whether 'prepare' has side effects, requires specific permissions, or is idempotent. This is partial but not full transparency.

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, front-loaded with the tool's purpose, and every sentence contributes: what it does, node flexibility, and where to get the final result. No filler or repetition.

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 tool with 2 parameters, full schema coverage, and an output schema, the description is adequately complete. It tells the user what to expect (metadata only) and directs to the follow-up resource, though it could briefly explain why this preparation step is needed versus calling get_blame directly.

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 coverage is 100%, so the description does not need to restate parameters. It adds the nuance that 'node' can be a unique partial name, but this is already present in the schema description. No additional parameter-level meaning is provided beyond the schema.

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-resource pair: 'Prepare one device's configuration blame' and identifies the target resource ('static get_blame'). It clearly distinguishes from siblings by focusing on blame preparation rather than configuration retrieval or diffing, and notes it returns only metadata.

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 clear context for when to use the tool: as a preparation step for get_blame, with node as exact or unique partial name. It directs the user to read oxidized://config/get_blame for the annotated config, effectively indicating the follow-up resource, though it does not name alternative sibling tools explicitly.

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