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

Beyond the read-only and non-destructive annotations, the description explains fuzzy matching behavior, transliteration handling, match_reason and score fields, strongest-first ordering, archived inclusion and flagging, and the include_archived override. This adds substantial behavioral context an agent would not get from annotations alone.

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 dense but front-loaded with the purpose and main matching behavior. The enumeration of match_reason values is lengthy, but it is useful for interpreting results and not mere filler.

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 search tool with no output schema and no schema parameter descriptions, it covers the important return fields, ordering, archived behavior, and a key usage scenario. It still leaves gaps around the limit parameter and no-query behavior, so it is strong but not fully complete.

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 0%, so the description must carry parameter meaning. It explains the fuzzy query fields, the optional tag filter, and include_archived behavior, but it does not explain the limit parameter or what happens when query is omitted.

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 gives a specific verb and resource: finding people in the caller's own contact book with fuzzy matching across names, aliases, transliterations, and other fields. It also distinguishes the tool from create_contact_personal by explicitly framing it as a pre-create duplicate check.

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?

It gives a clear use case: use before create_contact_personal to check whether a person already exists. It does not explicitly compare against list_contacts_personal or search_personal, so the alternative guidance is useful but incomplete.

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