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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered and the description needn't restate it. It adds genuine behavior beyond that: no results are returned, structured debug sections are produced, and invalid queries surface the FLECS parser error rather than failing opaquely.

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 purpose and the 'no results' constraint are front-loaded, followed by the returned sections and then the debugging use case. Four short sentences, each carrying distinct information with no redundancy.

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?

With an output schema present, the description need not explain return shapes, yet it still names the key sections and the optional profile. Purpose, usage trigger, result structure, and error behavior are all covered, leaving nothing an agent needs 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 both 'query' and 'profile' are already fully documented in the schema, including the ~1 ms repeated-evaluation behavior. The description only echoes the optional 'query_profile' output, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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 description states a specific verb and resource ('Explain how FLECS parses and plans a query') and immediately scopes it ('without returning results'), which cleanly separates it from the sibling flecs_query that presumably executes queries. An agent can identify the tool's role without opening any 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?

'Use it to debug queries that match nothing or match too much' gives a concrete condition for reaching for this tool. It stops short of naming the alternative (e.g. flecs_query) or stating when not to use it, so it is clear context without explicit exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral context: the return shape {entity, component, value}, the fact that value is reflection-serialized (usually a member object like {"x":10,"y":20}), and the three error conditions. That is more than the annotations convey.

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?

Three tight sentences, front-loaded with the purpose, then the return contract, then failure modes. No filler or repetition.

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 return-value explanation is technically redundant, but the note about FLECS reflection serialization adds nuance the schema likely cannot express. Combined with documented error conditions, the definition is complete enough, with only the sibling-differentiation gap remaining.

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 the dotted-entity-path and component/pair syntaxes are already fully documented in the schema. The description adds no additional parameter meaning, so the baseline 3 applies.

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 description states a specific verb and resource ('Get the value of a single component of an entity') and the '[READ]' prefix signals the operation class. It does not, however, distinguish itself from the sibling flecs_get_entity, which an agent might reasonably pick instead when it wants a component's value.

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?

Usage is implied by the 'single component' scoping and the error cases (missing component, tag with no data, unresolvable id), which hint at when the call will fail. There is no explicit guidance on when to prefer this over flecs_get_entity or flecs_query.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds real value beyond them: it errors when the entity does not exist, components are null when there is no reflection data, names are full paths, and entity_id/type_info/inherited/matches/doc are opt-in outputs.

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] prefix and a one-line purpose, followed by a compact enumeration of return fields and a closing routing sentence. The return-field list is somewhat lengthy given an output schema exists, but every sentence carries information and nothing is padded.

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 7-parameter read tool with full schema coverage, complete annotations and an output schema, the description covers purpose, alternative routing, error behavior and return shape. An agent has everything needed to invoke 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 description coverage is 100%, so every parameter including escaping of literal '.' and the '#523' numeric-id form is already documented in the schema. The description only restates that optional fields are included 'when requested', adding no syntax or format detail beyond the structured fields.

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 description opens with a specific verb and resource ('Get one entity') plus the [READ] tag, and enumerates exactly what is returned (tags, relationship pairs, component values). It also names a sibling ('flecs_query') so an agent can differentiate read-one from search-many without opening a 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?

It gives explicit guidance: use flecs_query to find entities, and use the 'matches' flag to diagnose why a system does or does not process an entity. It stops short of an explicit when-not-to-use rule, but the routing to the alternative is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: the FlecsStats module prerequisite, units (seconds), and the interleaving of sync points in execution order with a pipeline.

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 purpose, then structured detail on the entries payload and pipeline behavior. Every sentence carries information; slightly dense but no filler.

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?

With an output schema and full annotation coverage, the description only needs to frame purpose and behavior, which it does well, including the prerequisite module and return-field semantics. The main omission is comparative routing to sibling stats tools.

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 100%, so 'period', 'history' and 'pipeline' are already documented in the schema. The description reinforces pipeline ordering and the seconds unit but adds little syntax or semantics beyond what the schema fields state; baseline 3 applies.

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 ('Get per-system timing statistics from the FLECS stats module') with clear scope, and is readily distinguishable from the sibling flecs_get_world_stats by being per-system rather than world-level.

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?

Mentions the required stats module and explains that supplying a pipeline yields ordered systems including sync points, which is useful context. However, it never explicitly states when to prefer this over flecs_get_world_stats or the other stats/list siblings, leaving the choice to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds genuine behavioral meaning beyond structured fields: has_reflection=false yields schema null and means FLECS cannot serialize or set the value, which is a meaningful caveat for the caller.

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-loads the verb and resource in the first clause, then describes the return shape and edge case in tight prose. The inline example of the schema mapping is slightly verbose but earns its place by clarifying the descriptor format.

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?

With an output schema present, the description needn't fully describe returns, yet it usefully highlights the has_reflection/schema-null edge case. Annotations cover safety. The only gap is routing guidance relative to sibling tools.

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 one parameter and schema description coverage is 100%, so the schema fully documents 'component' including its dotted-path format example. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 ('Get') and resource ('reflection schema of a component type'), and immediately scopes it with '(members, types, units)'. This distinguishes it from siblings like flecs_get_component or flecs_list_components, which the agent can tell apart without opening either 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?

Usage is implied rather than stated: the description explains the has_reflection=false case, which hints at when the tool is useful, but never says when to prefer it over flecs_get_component or flecs_get_entity, nor lists prerequisites. No explicit when/when-not guidance or alternatives are named.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context beyond the structured fields: the tool fails outright if the REST API is unreachable, and any return section can be null with a 'notes' field explaining why (e.g. stats module not imported).

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 the primary action before any detail, which is exactly the right ordering. The bulleted return list is scannable, though it partially restates structure that an output schema already provides, so it earns slightly less than full marks for economy.

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 zero-parameter tool with annotation coverage and an output schema, this is complete: it explains the failure mode, the nullability of each section, and the diagnostic 'notes' field, while leaving return-value shape to the output schema. An agent has everything needed to call it correctly and interpret a degraded response.

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?

The tool takes zero parameters, so there is no parameter semantics for the description to carry; the 4 baseline applies. Nothing about the empty schema is misrepresented.

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 ('Describe the connected FLECS world') and immediately disambiguates it from siblings by scoping it to the world rather than an entity, component, query, or stats subset. It also fixes its ordinal role ('call it first'), so an agent can place it relative to the other ten tools without opening a 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?

Gives a clear when-to-use rule: call it first, as a connectivity/link test. It does not, however, address overlap with the close sibling flecs_get_world_stats, which appears to surface a subset of the same world_summary counters, and there are no explicit when-not conditions.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered; the description goes further by disclosing the stats-module dependency, the graceful failure mode, and that all time values are in seconds. That is exactly the kind of environment/auth-style context the annotations cannot express.

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?

Two sentences, front-loaded with the [READ] marker and the core action, then the metric key examples and the prerequisite. No filler, no repetition of the schema's parameter text.

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 return-value description is a bonus rather than a requirement, and the description nonetheless sketches the metric map. Combined with the module prerequisite and failure behavior, an agent has everything needed to call this 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 100%, so period and history are already fully documented in the schema and the baseline is 3. The description adds value above that baseline by explaining what the 'metrics' map keys look like and the {avg, min, max, brief} shape of each value, plus the seconds unit.

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 description opens with a specific verb+resource ('Get world performance statistics from the FLECS stats module') and enumerates the metric namespaces returned (performance.*, entities.*, tables.*, queries.*, commands.*, memory.*), which pins down the scope precisely. It does not explicitly distinguish itself from the sibling flecs_get_pipeline_stats, so it falls just short of full sibling differentiation.

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 states a prerequisite ('requires the FLECS application to import the stats module') and what happens when unmet ('returns an explanatory error otherwise'), which is genuinely useful gating information. However, it never says when to prefer this over flecs_get_pipeline_stats or flecs_get_world_info, so the use-case routing is only implied.

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

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.

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: every query is evaluated to build the list (a real performance cost), and the 'memory' field appears only when the stats module is imported. That is useful operational context beyond the structured hints.

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-loads the purpose and the [READ] tag, then enumerates fields efficiently. The field-by-field enumeration is somewhat redundant given an output schema exists, but the cross-reference and cost caveat justify most of the length.

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 listing tool with a full output schema, it covers what the schema cannot: the evaluation cost, the conditional stats-module field, and the downstream link to flecs_run_named_query. An agent has everything needed to call it correctly and interpret the result.

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 the schema already documents kind, limit, offset, include_plans and name_contains. The description adds no parameter-level syntax or filtering guidance, so the baseline 3 applies; it earns no extra credit here.

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 named queries, systems and observers') and names the exact scope of the results (evaluation statistics). It even ties the returned 'name' field back to the sibling flecs_run_named_query, so an agent can distinguish this discovery tool from the execution tool without opening either 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?

Gives clear context: use this to discover named queries/systems/observers whose names feed flecs_run_named_query, and warns that listing triggers full evaluation and 'can take a while in very large worlds.' It does not explicitly say when to prefer flecs_query, flecs_explain_query, or flecs_get_pipeline_stats instead, so there are no hard exclusions.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real value beyond them: it documents the failure mode ('Invalid queries return the FLECS parser error with position') and the paging completeness signal ('may_have_more'), which the annotations do not cover.

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?

Purpose is front-loaded, followed by the syntax reference and then the return shape, which is a logical reading order. The cheat-sheet block is long but every example encodes a distinct query-language feature, so it earns its space rather than padding.

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 complex query-language tool with 10 parameters, the description covers syntax, output shape, paging semantics, and error behavior. With an output schema already present it doesn't need to enumerate return values, yet its summary of the result fields is accurate and sufficient for correct invocation.

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 a baseline of 3 would suffice. The description earns a higher score by providing a full syntax cheat sheet for the core 'query' parameter and by explaining the table=true behavior and its effect on the returned shape, adding semantics beyond the terse schema descriptions.

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 description opens with a specific verb and resource ('Find entities with a query written in the FLECS query language'), making the mechanism clear. It is implicitly distinguished from the sibling flecs_run_named_query by taking an inline query, but it never names that sibling to make the contrast explicit.

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 gives concrete operational guidance for paging ('when may_have_more is true, call again with offset += limit'), which is genuinely useful. However, it never states when to prefer this tool over alternatives like flecs_run_named_query or flecs_get_entity, so usage is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered and the '[READ]' tag is largely redundant. The description does add the snapshot semantics ('matches now') and points to the result shape {page, results, type_info?}, which the annotations do not. No contradiction with annotations.

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?

Three short sentences, front-loaded with the read marker and core purpose, then use case, then return format. Nothing is padded, though the '[READ]' tag duplicates the annotation rather than earning its place.

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?

Given a full output schema and rich annotations, the description only needs to convey purpose, usage, and return shape, and it does all three. It stops short of routing between siblings (flecs_query vs. this vs. flecs_list_queries), which is the one gap an agent might still need.

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% across all 11 parameters, including good detail on 'name' (dotted path, example, cross-reference to flecs_list_queries) and the interplay between table/inherited/values. The description adds no parameter-level meaning beyond this, so the baseline 3 is correct.

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 ('Return what an existing named query, system or observer matches') and names the key constraint that the query already exists by name. It partially distinguishes itself from flecs_query by noting the shared result format, though it never explicitly contrasts the two (ad-hoc vs. named), leaving sibling differentiation implied rather than stated.

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?

'Useful to check which entities a system processes' gives one concrete scenario, which is better than nothing. But there is no explicit when-to-use/when-not guidance, no mention of when to prefer this over flecs_query or flecs_list_queries, and no prerequisites (e.g. that the name must come from flecs_list_queries). Usage is implied rather than directed.

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