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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive, closed world), so the bar is lower. The description still adds real context beyond them: the full shape of each persona entry, the cross-tool contract that the key is passed as `as` and a group name/id as `group`, and a privacy scope constraint. It does not mention ordering or pagination, but the output schema is present.

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 core purpose ('What the person RUNS on Hunchful — their personas') before the em-dash enumeration. The long middle clause is dense but each item (clubs, companies, channels, classes) earns its place by bounding the resource. Minor verbosity in the stacked parentheticals.

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 zero parameters, full annotation coverage, and an output schema that documents the return shape, the description's job is mostly framing and routing - which it does well, including privacy scope. It is complete enough to call correctly; the absence of a named sibling alternative is a small 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?

The tool takes zero parameters, so the baseline is 4. The description usefully references parameters of other tools (`as`, `group`) that consume this tool's output, which is cross-tool context rather than this tool's own parameter semantics.

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 (list/read) and resource (personas = clubs, companies, channels, classes) and enumerates exactly what each persona record carries (key, role, channel, post permission, led groups). It explicitly distinguishes itself from neighbouring concepts by noting the friends channel and CV are 'not here', so an agent can separate it from list_friends / list_identities.

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 entry-point directive ('Start here for anything about what they run') and an explicit exclusion (friends channel and CV are not included). It also explains how the returned key feeds the `as` parameter of other tools, routing the agent downstream. It stops short of naming a specific sibling alternative for an overlapping query.

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