People Directory

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds behavior the annotations cannot: that 'user' returns manager and direct reports, and that 'groups' is scoped to the signed-in user's memberships. It omits auth/permission requirements and pagination behavior, keeping it out of 5 territory.

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?

A single front-loaded sentence gives the purpose first, then the three modes in order of likely use. Every clause carries distinct information; there is no filler or repetition of the title.

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?

With no output schema, the description usefully sketches what each mode returns (email resolution, person details plus manager/reports, memberships), and annotations cover the safety profile. Minor gaps remain: no guidance on what happens with zero parameters, no pagination note, and 'count' is unaddressed, but nothing blocks a correct call.

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. The description exceeds that by tying each parameter to an outcome and a purpose — 'search' exists specifically to resolve a name to the email address ms_schedule requires — which is meaning the schema text does not carry. 'count' is left to the schema, which is acceptable given its self-explanatory bounds.

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 ('Look people up in the organisation directory') and then enumerates the three distinct operations the tool supports (search, user, groups). This lets an agent distinguish it from siblings like ms_profile or ms_search without opening the schema.

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 the tool's three modes and names a concrete downstream consumer ('the input ms_schedule needs'), which is genuinely actionable. It stops short of stating when NOT to use this tool versus lookalike siblings such as ms_profile, so it is clear context rather than full when/when-not guidance.

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