introduce_factory

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: 'Existing constructor calls across the project are rewritten to the factory' (a side effect), the default Dry Run mode, the use of apply to write, and the fail-safe behavior of expected_symbol. It also clarifies the tool's scope ('this tool only changes code'), making side effects transparent.

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 description is four dense sentences, front-loaded with the core purpose. Every sentence provides essential information: the action, location semantics, default vs. global factory behavior, dry-run/apply, expected_symbol safety, and the prerequisite LSP step. There is no redundancy or 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?

Given the tool's complexity (8 parameters, project-wide effects), the description covers prerequisites, safety, side effects, and parameter nuances. The presence of an output schema makes it unnecessary to describe return values. The note to locate the class with LSP first is critical contextual guidance. Overall, it is a complete and robust description.

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?

The description adds meaning beyond the schema for most parameters: it explains factory_name ('static method named factory_name'), global_factory ('creates a module-level function instead'), apply ('set apply=true to write'), and expected_symbol ('so a stale Position fails safely'). It also explains line/character positioning. However, it does not explicitly mention the 'file' parameter or the optional 'root' parameter, leaving a minor gap for a required input.

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 clearly states the tool's function: 'Introduce a factory for a class and route instantiations through it.' It also specifies the target ('Point at the class name') and the project-wide effect ('Existing constructor calls across the project are rewritten to the factory.'). The verb+resource+scope is specific and distinguishes this from sibling refactoring tools.

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 explicit when-to-use guidance: 'Locate the class with your LSP first; this tool only changes code.' It also explains how to control behavior: 'Defaults to a Dry Run preview; set apply=true to write' and when to supply optional parameters: 'Supply expected_symbol when edits may have intervened since your LSP answer.' This is clear operational context with no ambiguity.

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