lib_run_across

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

With no annotations, the description carries the full burden and does so: it discloses that the loop runs inside Altium, that failure is isolated per library rather than aborting the sweep, and that the reply reports per-library status so partial success is visible. It also bounds the cost model (document open/save is not saved) and clarifies timeout scope.

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?

Front-loaded with the core statement, then headed sections that scan well. A few clauses are discursive ("which is what makes a twenty library sweep tedious rather than slow") and the Returns block partly restates the output schema, but no paragraph is truly wasted.

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 4-parameter fan-out tool with no annotations, the description covers eligibility, failure semantics, timeout scope, and the cost tradeoff — everything needed to call it correctly. Return values are also summarized despite an output schema existing, which is redundant but harmless.

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%, so the description must compensate, and it does for all four parameters: action examples plus the namespace-stripping rule, libraries as full paths with the "|" join detail, params as shared with per-library library_path override, and timeout as whole-sweep rather than per-library. The only shortfall is that action eligibility is described by category rather than enumerable list.

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 opening line states a specific verb and resource — run one library command against many libraries in a single call — and implicitly contrasts with the many single-library siblings (lib_get_components, lib_batch_rename). An agent can tell immediately that this is a fan-out wrapper rather than another library operation.

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?

It names the eligible action class ("those that accept a library_path, which is most of the read and batch-edit commands") and explicitly excludes the footprint EDITING commands with the reason (create_footprint, add_footprint_pad, link_3d_model act on the open document). It also states what the tool does not save, so the agent can judge whether the sweep is worth it.

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