statsfm_artist_affinity

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

With no annotations available, the description carries the disclosure burden and does well: it states 'Read-only, no auth' and explains the underlying metric construction (lifetime intensity plus a recency half-life). It could also mention output format or failure modes, but the core behavioral and safety-relevant traits are covered.

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 compact: a hook question, a two-part metric explanation, and a read-only/auth note. Every sentence earns its place, though the opening question is more stylistic than informative.

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?

The description explains the methodology and auth posture, and the schema fully documents all three parameters. However, there is no output schema and the description does not describe the return shape or how the 'response_format' parameter changes results, which leaves an agent partially guessing about the tool's output.

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 baseline is 3. The description does not add parameter-specific meaning beyond the schema, though it does convey the overall metric concept. It neither repeats the parameter docs nor clarifies how the two required parameters interact.

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 indicates it computes an artist affinity metric using lifetime stream share and recency half-life, and it is marked as read-only with no auth. It does not use a direct verb like 'calculate' or 'get', and it does not distinguish itself from the similar sibling 'artist_affinity', so it is not fully unambiguous.

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 conveys a clear use case: measuring how deeply an artist is listened to over time, with no auth required. However, it does not explicitly state when to choose this tool over related statsfm siblings like artist_affinity or statsfm_artist_stats, nor does it give exclusions.

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