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

With readOnlyHint already covering safety, the description adds substantial non-obvious behavior: visibility scope (own characters plus public catalog; other accounts' projects never appear, projects can be confidential; new characters are private), result limits (max 50, newest first, no paging, 20 shown, total understates), and that search is the only route to older sheets.

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?

Front-loaded with what the tool does and when to call it, then layers limits, privacy scope, and the fallback alternative. Dense but every sentence carries information; slightly long for a two-parameter read tool, keeping it just below the top mark.

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?

There is no output schema, so the description must carry the return contract, and it does: it lists returned fields, the 50-sheet ceiling, newest-first ordering, no paging, and why total can understate. Nothing needed to call or interpret the result is missing.

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; both the search semantics (substring, case-insensitive) and the preview constraints are already documented in the schema. The description restates that search is optional and is the only way to reach older sheets, which is context rather than new parameter meaning.

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?

States a specific verb and resource (list character sheets in the FilmLab cast register) and enumerates the returned fields (id, name, age, gender, project_name, prompt_prefix_en). This is easily distinguished from siblings like lab_get_character, lab_get_character_sheet, and lab_create_character.

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?

Gives an explicit trigger: 'Call this BEFORE lab_generate whenever a person must look the same across several images', and explains the mechanism (pass the id as character_refs instead of re-describing). It also names the alternative for the empty case ('Nobody there yet? Create a sheet with lab_create_character').

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