list_graph_entities

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

The annotations declare readOnlyHint=true (no environment modification), but the description states 'Only reads, apart from creating the workspace if it doesn't exist' and the schema adds that the call is recorded as a job in that workspace's history. Those are real write side effects, so the description's own carve-out directly conflicts with the read-only claim. Aside from the conflict, the disclosure of return shape and sort order would otherwise be high-value.

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 in the first clause, and the second sentence packs useful routing and return-shape information rather than filler. It is dense (a full field list plus three cross-references) but no sentence is 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?

There is no output schema, so the description must describe the return value, and it does: an array of { id, type, name, attributes, artifactIds, createdAt, updatedAt } with the class-specific attributes.file note. Combined with sort order, side-effect disclosure, and sibling routing, nothing an agent needs to call this 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% and all three parameters (q, type, workspace) are already documented there, including the type enum values and the workspace creation side effect. The description adds only sorting ('sorted by name') and no extra filtering syntax, so 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?

Specific verb + resource + scope: 'List the typed entities in a workspace's knowledge graph, sorted by name', and it goes on to define what those entities are (packages/classes from a jadx decompile plus Gateway-API additions). It is cleanly distinguishable from the singular sibling get_graph_entity, which the description itself names.

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 routes the agent explicitly: 'Use get_graph_entity for one entity's relationships, and an entity id as entityId in a finding's evidence', which links this tool into the findings workflow. What's missing is when-not guidance (e.g. when to prefer search_code or a filtered q/type query instead of a full listing).

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