Get one performer

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

The description adds meaningful context beyond the annotations: it explains that the tool merges records from multiple catalogues, presents disagreement resolution ("where they disagree the reading nobody preferred is published beside the one that won"), and the 'prefer' parameter's effect. While annotations declare readOnlyHint=true and openWorldHint=true, the description's catalogue-merge explanation is distinctive. However, the phrasing is obfuscated — terms like 'card', 'reading', and 'nobody preferred' are used in non-standard ways without being explicitly defined.

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 a single dense paragraph that is somewhat RAMBLING. The first sentence introduces the core purpose, but the subsequent three sentences are long, nested, and contain an extended metaphor that requires significant cognitive overhead. Some sentences are 40+ words and include unusual phrasings like 'the answer is one card, read on every catalogue that holds the record and reached by the link each of them publishes to the same record elsewhere.' The entire description could be more concise with clearer, plainer language, lending to a lower score on structure.

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 tool with no output schema, the description makes a fair effort. It explains the merged-catalogue output, the role of the 'prefer' parameter in resolving disagreements, and the semantics of the 'sources' parameter. The tool's complexity is medium, given the merge logic. The description doesn't lack for explaining the returned data; the main issue is the overly florid language which, while adding context, requires effort to parse. Given the presence of an output schema (as evidenced by 'Has output schema: true'), the threshold for completeness is lowered.

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?

With 50% schema coverage, the description partially helps: it explains the 'sources' parameter and mentions the 'prefer' ordering, but it doesn't cover the 'sections' parameter at all and describes 'id' only by example ('instance:uuid'). The 'prefer' parameter is mentioned but not by name. The id parameter's uuid format is partially covered by the schema's pattern, and the description adds the notion of a qualified instance:uuid. This adds some value but doesn't fully compensate for the 50% coverage gap, hitting the baseline of 3.

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 begins with a specific transitive verb and object: "Read one performer from the catalogue its identifier names, written instance:uuid." This clearly states the tool retrieves a single performer by ID, distinguishing it from siblings like search_performers (which searches). However, the sentence is grammatically awkward ('catalogue its identifier names'), and the latter half of the description shifts into a confusing metaphor about cards, catalogues, readings, and disagreements that obscures rather than clarifies the tool's core purpose.

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 explicitly contrasts with the alternative 'sources' parameter: "Name 'sources' to read one catalogue alone." This tells users when to use the sources parameter versus the default merged view. While it doesn't explicitly name sibling tools like get_sources, it clearly explains the two modes of operation. However, it doesn't explicitly say when to prefer this over search_performers, though the read-vs-search distinction is implied.

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