Search members

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real behavioral detail beyond that: results are rank-ordered 'best matches first' and matching is on name or handle (substring, per the schema). It does not mention pagination limits or empty-result behavior, keeping it short of a 5.

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 the core action and sized appropriately for a read-only search tool. The '@mention box' analogy is stated twice in nearly identical wording ('as the @mention box does' / 'as typing @ in a post does'), which is one sentence of redundancy in an otherwise tight definition.

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 3-parameter read-only search with no output schema, the description covers purpose, ranking, matching fields, and the shape of the useful return value (member_id). Only minor gaps remain: the existence of other returned fields (name, handle) and result-limit behavior are left implicit.

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 and the description must earn more. It does so by clarifying the matching semantics of `query` (name or handle) and, critically, by identifying `member_id` as the returned key that get_member and send_message consume — bridging input to downstream usage in the absence of an output schema.

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 ('find members of a group by name') plus a concrete analogy ('as the @mention box does') that pins down the exact search semantics. Immediately distinguishable from list_members (paging everyone) and get_member (lookup by id), both named in the text.

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?

Explicitly routes the agent among siblings: use this for name/handle search, get_member and send_message when you already hold a member_id, and list_members to page through everyone. That is a complete when-to-use-this-vs-alternatives map with no inference required.

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