analysts

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

With no annotations provided, the description carries the transparency burden, and it delivers meaningful context: stats are '100% real', computed from the live signalHistory table, winRate is a fraction, and avgReturn is a percentage. It also explains the non-human attribution model. It could explicitly state it is a read-only listing, but the 'Returns...' framing and data-source disclosure cover the most important behavior.

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 description is front-loaded with the core statement and the persona enumeration is useful rather than filler. However, it is lengthy and ends abruptly with a stray 'B' (likely truncation), which breaks the structure and leaves an incomplete trailing thought.

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 simple zero-required-parameter listing tool with no output schema, the description explains what is returned, lists all expected personas, and defines the two key stat formats. The optional filter is fully covered by the schema, so nothing essential is missing for calling the tool 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?

The schema already documents the optional analyst enum filter with 100% coverage, so the baseline is 3. The description adds persona display names that roughly map to enum slugs, but does not discuss the filtering behavior or parameter format, so it neither helps nor hurts 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 names a concrete resource and action: it 'Returns all 10 pseudonymous ... analyst personas' and enumerates every persona with its domain, so an agent knows exactly what this tool provides. The 'all 10' phrasing also sets it apart from sibling analyst tools like analysts_top or analysts_signals even without naming them.

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?

The description implies the tool is for getting the full analyst roster with live performance stats, and clarifies the analysts are algorithmic identities rather than humans. However, it never explicitly says when to use this over sibling tools such as analysts_signals, analysts_top, or analyst_archive, leaving selection to inference.

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