users_read

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable dispatch behavior: it reveals the tool multiplexes 8 named endpoints and that the caller must pass the endpoint name in `name`, which is operational context beyond annotations.

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?

One compact paragraph, front-loaded with purpose, then the endpoint list, then call instructions. No filler; the endpoint list is dense but necessary for dispatch.

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?

Given no output schema and full parameter schema coverage, the description supplies the essential dispatch mechanics and points to list_endpoints for full details. It does not explain per-endpoint body/query/path requirements, but the schema covers those fields adequately.

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 coverage is 100%, so the baseline is 3. The description adds meaning for the `name` parameter by listing the exact 8 endpoint names, supplementing the schema's generic 'from list_endpoints' text. Other parameters are left to their schema descriptions.

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 'Read operations on Fivetran users' and enumerates the 8 endpoints, so the verb, resource, and scope are clear. It does not explicitly contrast with sibling resource-read tools, but the tool name and endpoint list make its domain 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?

Provides a discovery hint (call list_endpoints(category='users') for the full list) but does not state when to choose users_read over sibling *_read tools or when not to use it. Usage is implied by the users domain but not explicitly guided.

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