proj_replace_component

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

No annotations exist, so the description carries the full burden. It does disclose the key mutation semantics (connections and designator preserved, symbol/library ref swapped) and the sheet precondition, which is real value. It omits what an agent would want next for a destructive-ish swap: behavior when the designator is not found, whether the new library reference must already exist, and — critically for an EDA tool — whether the PCB footprint link is affected or a re-sync is required.

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 behavioral summary is front-loaded in three tight sentences, followed by Args/Returns. No filler. The Args block mildly restates parameter names already in the schema, but the added examples earn most of the space.

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 the Returns note is redundant but harmless, and parameter meaning is covered. What is missing is the side-effect surface expected of a schematic mutation in a project toolchain: footprint/re-link consequences, failure modes, and whether a project compile or PCB sync is needed afterwards.

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 0% (properties carry only bare titles), so the description must compensate, and it largely does: it explains each parameter in prose and adds examples for designator ("U1", "R3") and the optionality semantics of new_library ("keeps current if empty"), which the schema's bare default does not convey. It stops short of stating format constraints on library references (e.g., 'Library:Part' syntax).

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 and resource ('replace a component with a different library part') and immediately clarifies the semantics of the swap: connections and designator preserved, symbol and library reference exchanged. This is materially distinct from siblings like sch_replicate_component or obj_modify, so an agent can select it without opening the schema.

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 one precondition — the component must exist on the active schematic sheet — which is genuinely useful scoping. However it names no alternatives and no when-not-to-use cases (e.g., whether to use obj_modify for parameter-only changes, or re-sync the PCB afterwards), so usage is only implied.

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