identity_search_users_in_idp_by_names_and_email

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the description's job is to add context — and it does add two things that matter: the deprecation status and the role-based access table (Platform operator, Org Owner, Org Member, Service Account). It discloses nothing about result behavior (ordering, matching semantics for name vs. email, truncation), and the readOnlyHint=false on a pure search may confuse an agent, though the disclosed 'POST' verb makes the annotation consistent with an HTTP-derived hint rather than a contradiction.

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 critical information (deprecation) is correctly front-loaded, which is the right structure. But a large markdown access-policy table and a raw endpoint path consume most of the description's length for boilerplate that adds little to tool selection, and the sentence flow is fragmented by markdown headers embedded in a prose field.

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?

Deprecation, replacement, access roles, and HTTP binding are all covered, which is more than many definitions offer. With no output schema, though, the description should say something about the response shape (list of users, paging envelope tied to pageStart/pageLimit), and for a nested-body search tool it leaves the result contract entirely 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 description coverage is 100% and every nested body field (idpId, domain, pageLimit, pageStart, searchTerm) already carries a description with defaults and constraints, so the baseline of 3 applies. The prose adds no parameter meaning beyond the schema — notably it does not clarify how searchTerm matches across first name, last name, and email in practice.

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 with scope: 'Search users in idp by names and email', matching the tool name and distinguishing it as an IdP-scoped name/email lookup. However, it never distinguishes itself from near-identical siblings in the toolset such as identity_search_users, provider_search_ldap_users, or provider_query_users, so an agent still has to guess which search to use.

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 does provide explicit negative guidance ('[DEPRECATED] ... Use this API instead: /scim/v2/Users'), which is a genuine when-not-to-use signal. But the recommended replacement is a raw REST path, not one of the available sibling tools, so the agent is steered away without being steered toward a callable alternative, and there is no guidance on when IdP search beats the other search tools.

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