search_users

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It does disclose one significant behavioral trait: 'Only returns publicly visible users,' which clarifies the tool's scope. However, it does not mention potential rate limits, authentication requirements, pagination behavior, or the structure of the response, which are relevant for a search API. This is partial transparency but leaves gaps.

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 description is extremely concise: two sentences and a documentation link. It front-loads the core purpose ('Search GitHub users') and immediately adds the most important constraint ('publicly visible'). The remaining sentence provides a useful example and a link. No wasted words.

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?

As a search tool with no output schema, the description does not explain the return format, but it does include the essential context: what is searched, the key constraint (public users), and the supported query qualifiers. Pagination is implied by the schema's page/per_page parameters, which description doesn't need to repeat. Given the tool's relative simplicity and the clarity of its purpose, this is quite complete, though a note about the response structure would push it to 5.

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?

The schema already describes the q parameter and enums for sort/order, with 60% coverage. The description adds value by clarifies the query syntax with a concrete example ('tom repos:>42 followers:>1000'), which is not fully evident from the schema alone. It also points to official documentation for qualifiers. This goes beyond the schema, so a 4 is appropriate.

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 clearly states the tool's purpose: 'Search GitHub users.' This uses a specific verb (Search) and a specific resource (GitHub users), distinguishing it from sibling search tools like search_repos, search_commits, and search_issues. It also adds a key scope constraint: 'Only returns publicly visible users.'

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?

The description provides clear guidance on how to use the tool by explaining that the q parameter accepts GitHub user-search qualifiers and giving a concrete example ('tom repos:>42 followers:>1000'). It also links to official documentation. However, it does not explicitly mention when to use this tool instead of other search tools, though the resource ('users') makes the context fairly obvious.

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