list_factories

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds two behavioral facts: results are scoped to the current world, and each entry includes a degradation/status figure. It says nothing about ordering, pagination, or what happens for worlds with no factories.

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?

A single front-loaded sentence with a clarifying parenthetical; nothing is padding. The closing phrase 'how much of each still stands' is evocative but slightly vague about the actual metric returned.

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?

Adequate for a simple zero-required-parameter read with no output schema, and it does communicate the return shape at a high level. However, with three optional parameters whose interplay (current vs. pinned world/save) is unexplained, an agent still has to guess about defaults and scope selection.

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?

Only 33% of the schema is documented (as_of alone), and the description does not compensate: the 'world' parameter is only obliquely gestured at via 'this world', and 'save' is never mentioned or distinguished from as_of, even though both appear to be optional save-pinning knobs. An agent cannot tell from this text what leaving them null does.

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+resource (list named factories) scoped to 'this world', and adds that each entry carries a completeness/status measure ('how much of each still stands'). It implicitly distinguishes itself from siblings like factory_health or factory_query by returning names plus status, though it never names those siblings explicitly.

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 parenthetical '(the names factory= takes)' is a useful usage cue: call this to discover the factory identifiers other tools expect. But there is no explicit when-to-use/when-not guidance and no named alternative among the many factory-related siblings (factory_map, factory_sites, factory_query).

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