get_r_user_get_users

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

No annotations are provided, so the description must fully disclose behavioral traits. It only says 'Retrieve Users' and mentions it is a GET call, which implies read-only, but it does not mention authentication requirements, pagination behavior, rate limits, or any side effects. There is no indication of whether the operation is safe or what the response contains (though an output schema exists). The description leaves the agent to infer too much.

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 two sentences, front-loads the action, and includes the endpoint. It is efficient with no fluff. The parameter placement instructions are structured logically, though they could be more explicit. It is appropriately concise for the tool's complexity.

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 GET tool with four generic parameters, the description is insufficient. It does not specify what filters are available, what 'route IDs' mean (e.g., user IDs?), or how pagination is performed. It also omits authentication details and any error handling. The output schema covers return format, but input semantics remain vague. An agent would struggle to construct correct calls without additional context.

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 0%—the schema has generic objects with no property definitions. The description adds some meaning by indicating that path_params should contain route IDs, query should contain filters and pagination, and headers for required request headers. This is a helpful high-level mapping but lacks specificity (e.g., which filters are supported, pagination syntax, or what route IDs refer to). It partially compensates for the schema's opaqueness but not fully.

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 action ('Retrieve Users') and the specific resource, backed by the explicit endpoint `GET /r/user/get_users`. This distinguishes it from sibling tools that target companies, assets, reports, etc., even though it doesn't name an alternative. It is straightforward and unambiguous.

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 only gives instructions on where to place parameters ('path_params', 'query', 'headers') but does not explain when to use this tool instead of others or any exclusions. There is no context about the intended use case, prerequisites, or selection criteria relative to similar retrieval tools. This is essentially parameter placement guidance, not usage guidance.

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