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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds the specific return field list and mentions snapshot metadata, giving the agent an accurate expectation without needing to call the tool. This adds useful context beyond the annotation bundle.

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 entire description is one efficient sentence that front-loads the core action and resource, then enumerates the returned fields. There is zero redundant phrasing or filler. Every word earns its place.

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-record lookup with a single parameter, the description adequately covers what is returned and the lookup key. No output schema exists, so listing the returned fields is helpful. It does not detail snapshot metadata contents or possible error behavior, but these are minor gaps given the tool's simplicity.

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 input schema fully documents the slug parameter with an example, achieving 100% coverage. The description naturally references the slug but adds no additional semantic detail such as format requirements or edge cases. With complete schema coverage, the baseline of 3 is appropriate.

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 ('get'), resource ('one artist's oTDH'), and enumerates the exact data returned (rank, score, collector breadth, raw collector-days, project count, snapshot metadata). It also specifies the lookup key (AB5D artist slug). This clearly distinguishes it from the sibling list_artist_otdh, which likely returns multiple artists.

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 phrase 'one artist's' makes the singular scope explicit, implying this tool is for a single record while list_artist_otdh is for multiple. However, it does not explicitly name the alternative or state when to choose one over the other. The context is clear enough for an agent to infer the selection rule.

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