list_clusters

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail above annotations: the read-only label reinforces safety, and it explains the dual-mode behavior (list vs open) and how project titles span all themes. It doesn't disclose return format or pagination, but the annotated safety profile and mode explanation cover most of the behavioral burden.

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 tightly-scoped sentences, zero filler. Every sentence earns its place: mode 1 (no-arg galaxy view), mode 2 (open with cluster=), and the pairing tip with recall_memories. Front-loaded with the purpose verb and immediately readable.

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 single-parameter tool with no output schema and strong annotations, the description is complete. It covers both invocation modes, the pairing workflow with recall_memories, and read-only safety. The complexity is low and fully documented. There is no return-format requirement since output_schema is absent but the tool is simple enough that this isn't a gap.

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% — the schema already documents the cluster parameter (title case-insensitive or UUID, omit to list). The description adds the dual-mode orchestration detail (open vs list) and mentions case-insensitivity is in the schema. Baseline 3 for full schema coverage is appropriate; the description reinforces but doesn't substantially expand 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?

The description clearly states a specific verb+resource ('Browse/list clusters') with an explicit two-mode behavior: no-arg listing of PROJECT -> THEME hierarchy with counts, and cluster= argument that opens a cluster and lists its member memories. It distinguishes itself from siblings by naming recall_memories as the semantic-search companion and from get_memory_details as a different level of granularity.

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?

Provides explicit when-to-use guidance: 'use this to show what projects/topics do I have?' and explains the open vs list modes with cluster=selector behavior. Names the pairing companion recall_memories(cluster=...) explicitly for semantic search afterward, giving clear context on when this tool vs alternatives is appropriate.

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