Author or translator

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavioral information beyond them: the book list is unfiltered by credit type, so an agent will not wrongly assume the list is only authored works. It still omits whether a missing profile errors or returns empty, and it does not mention pagination limits beyond what the schema states.

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?

Two sentences, front-loaded with the core action and followed immediately by the caveat that most affects interpretation of the result set. No filler and nothing restated from the schema.

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?

With five parameters, a required profile input, and no output schema, the description does what matters: it names the return content (name, biography, and books) and flags the credit-type ambiguity in the book list. It lacks fallback and error behavior for an unknown profile and does not restate pagination, which the schema already covers well.

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 each parameter, including profile, page, sort, term, and bio_chars, is already documented, including the profile-id source and page size. The description adds only partial meaning: it lists the returned fields but explains none of the parameters. The baseline 3 is correct here.

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 uses a clear, specific verb and resource: it says to read an author's or translator's profile (name, biography) and the books they wrote or translated. That is more precise than the title alone. However, it never states what distinguishes this tool from siblings such as ik_book or ik_search, so an agent still needs to infer the boundary between 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 second sentence warns that the returned book list mixes every credit type (writer, translator, and so on), which is useful usage context for interpreting the results. However, the description gives no explicit guidance on when to call ik_profile instead of ik_search(kind='profile') or ik_book; only the profile parameter's schema description implies that dependency.

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