Show Current Company User

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds that it returns a paginated JSON array with pagination metadata and mentions required parameters and API version. However, it does not note that it returns details of the current user specifically, nor does it explain behavior on invalid company_id or edge cases.

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 concise at four sentences, front-loading the purpose and then explaining pagination, required parameters, and API details. However, the first sentence is slightly ambiguous, which detracts from clarity.

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 three parameters, no output schema, but rich annotations, the description covers purpose, pagination, and required parameter. However, the inconsistency between 'current Company User' and 'specific Directory records' harms completeness. It lacks an explanation of what the tool actually returns (the current user's details).

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?

All three parameters are fully described in the input schema (100% coverage). The description adds value beyond schema by explaining how to use page and per_page to control pagination and that the response includes pagination metadata. This provides actionable usage context.

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 states 'Show detail on the current Company User' and mentions fetching full details of a specific Directory record, but there is inconsistency: 'current Company User' suggests the authenticated user, while 'specific Directory records' implies any record. The endpoint is /me, which returns the current user, not an arbitrary record. This muddles the purpose. Among siblings like show_company_user_v1_3, there is no differentiation.

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?

No explicit guidance on when to use this tool vs alternatives like show_company_user_v1_3. The description says 'Use this to fetch...' but does not specify context, exclusions, or mention other related tools. An agent would have to infer the use case from the endpoint.

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