Find Recipients

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's added value is the permission scoping ('people you are allowed to message') and the return content (user IDs). It doesn't mention pagination/truncation behavior or whether results include names and roles, which would matter when limit is hit.

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?

Three short sentences, zero waste, with the core purpose and read-only nature front-loaded and the sibling relationship last. Nothing redundant with 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?

For a no-output-schema, 3-param search tool this is nearly complete: it names the input filter, the optional course scope, and the return value. Minor gap: no note on result shape beyond IDs (names, roles, disabled/inactive users) or behavior when no matches are found.

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 baseline is 3, but the description adds real semantics: search is a name-based lookup and course_id is an optional narrowing filter. It still doesn't characterize match behavior (prefix vs substring) or what limit does to result ordering.

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 ('Search by name for people you are allowed to message'), scopes it ('optionally within one course'), and explicitly distinguishes it from the write-side siblings send_message and add_recipients. An agent knows exactly what this does and where its output feeds.

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?

Clear usage context: it's the lookup step whose user IDs 'send_message and add_recipients need', which implies when to call it. No explicit when-not or prerequisite caveats (e.g., whether a prior send attempt can fail without this lookup), so it falls short of full routing guidance.

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