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

Goes well beyond the readOnly/idempotent annotations by disclosing the login and OWNER/ADMIN role requirement, that phone search is unsupported, that members/pending-invite/30-day-declined/removed each carry status labels, and that same-named people must be disambiguated via headline/city.

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-loads the critical auth/role requirement and packs high-value constraints (invitable-only, status labels, next-step tool) into tight phrasing. Dense but every clause carries information; the bracketed tag format is compact.

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 read-only candidate search with no output schema, the description supplies everything an agent needs: eligibility rules, default behavior, disambiguation caution, status interpretations, and the follow-up action.

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?

With 100% schema coverage the baseline is 3, but the description adds real meaning on top of the schema: it clarifies the semantics of an omitted q (non-member activity participants) and adds a constraint (no phone-number search) that the schema does not state.

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+resource (find people who can be invited into the org) with scope qualifiers (by nickname/ability/bio, defaults to non-member activity participants) and distinguishes it from the sibling it feeds into, invite_organization_members.

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 clear context: only 'invitable' results can be invited, and explicitly routes the agent to invite_organization_members after confirming the list. Also notes the no-q default behavior and that phone numbers aren't supported. It lacks an explicit contrast against a sibling like search_people, so it falls just short of 5.

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