Read a person's record

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the description adds valuable behavioral nuance beyond that: it lists exactly which fields are returned (dates, places, occupation, language, country, Dewey class, external IDs), explicitly calls out what is absent (biography, works), and clarifies the unreliable nature of the 'biographical information' field. It also describes depictions as images the server does not read and that they may not be portraits, all useful behavioral context.

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 lengthy but every sentence serves a purpose: defining the record type, enumerating contents, clarifying omissions, warning about a misleading field, explaining the works limitation, and caveating depictions. It is front-loaded with a clear verb+resource and maintains a logical flow, with no redundant or filler sentences.

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?

Given the tool's moderate complexity, the annotations, full schema, and output schema, the description covers all essential aspects: what is returned, what is not, how to interpret ambiguous data, source of the identifier, and limitations of depiction links. It also contextualizes the tool within the sibling set, making it complete for an agent to select and invoke 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the author_id is the search_authors identifier and elaborates on depictions, including that the server does not read them and they can be misleading. However, the parameter schema already contains detailed descriptions for include_depictions (default, reason, alternative tool), so the description adds limited additional parameter semantics, earning a 4 rather than a 5.

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 opens with a specific verb+resource: 'Read one person's record in the Bibliothèque nationale de France authority file' and specifies the identifier source ('by the identifier search_authors returns'). It distinguishes itself from siblings by explicitly stating that search_works reads titles rather than authors and that no tool walks the author-to-works link, positioning get_author's scope precisely.

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 provides explicit guidance: use it after search_authors, and avoid using it to get works or biographies. It states 'It does not list the person's works' and points to search_works as the alternative, plus it warns how to interpret the 'biographical information' field to prevent misuse. This is clear when-to-use and when-not-to-use guidance.

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