Flecs List Components

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so this only needs to add context beyond that. It does: it discloses that FLECS builtin ids and wildcard records are included, that 'type' is absent for tags, and that 'memory' appears only when the stats module is imported — genuinely useful behavioral caveats.

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 [READ] tag and one-line purpose, then structured field-by-field detail. The entry-field enumeration is dense but earns its place by telling the agent what each record contains; slightly more verbose than strictly necessary given an output schema exists.

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 paginated read lister with annotations and an output schema, the agent has everything: what is listed, what each entry holds, what is included (builtins, wildcards), and which sibling to use for member schemas. Nothing needed to invoke it correctly is missing.

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 description coverage is 100%, so limit/offset/name_contains are fully documented in the schema itself; baseline 3 applies. The description's note that 'total counts matches after filtering' marginally clarifies filter semantics but adds no syntax or format detail beyond the schema.

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: 'List the component, tag and pair ids in use, with storage statistics.' Scope (in use) and the [READ] marker distinguish it clearly from siblings like flecs_get_component (single component) and flecs_get_type_info (member 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?

Explicitly routes the agent: 'Use flecs_get_type_info for a component's member schema', clearly delineating this listing tool from the schema-introspection sibling. No explicit when-not conditions or guidance on paging toward other listers, but the primary alternative is named.

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