describe_extension

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

With no annotations, the description carries the burden and does so well: it explains the three data sources, that installed+enabled+registering-nothing means a dead import, that update_available is answered without a fetch, and that ambiguous names are refused rather than guessed. It does not explicitly state that the call is read-only/side-effect free.

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 a one-line summary, then structured paragraphs covering sources, failure interpretation, routing, and args. Slightly long, but each sentence adds actionable information rather than restating the schema.

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 return values need not be explained, yet the description usefully frames what the returned fields mean (disk commit, registry version, registration state, declared dependencies). Combined with the parameter semantics and sibling routing, an agent has everything needed to call it correctly.

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% and the schema only says 'Name', but the description's Args block compensates: name accepts a folder name, registry id, or a distinctive substring, and ambiguity is refused. That is real matching semantics beyond the schema, though the exact disambiguation behavior on partial matches is left implicit.

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?

Specific verb (describe) plus specific resource (one installed node pack) and an explicit scope ('Everything known about...'). It clearly distinguishes itself from list-style siblings like search_extensions and from describe_environment by framing itself as the per-pack aggregation of disk, registry, and /object_info.

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?

Gives a clear reason to call ('the disagreements between them are the reason to ask') and routes specific sub-questions to siblings: get_comfy_log for import failures and plan_packages for dependency impact. It never states when NOT to use it, so it stops short of full alternative coverage.

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