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

The description discloses the return values, notes that email is best-effort and may be null, and mentions the underlying endpoint and authentication requirement. It does not describe error conditions or rate limits, but for a simple identity getter the behavior is sufficiently transparent. Annotations are absent, so the description carries the full burden, but it covers the essential behavioral aspects.

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 structured into clear paragraphs with bold emphasis on key terms like userId and email. It is slightly verbose but each sentence adds meaningful information—no filler. The length is acceptable given the nuance about identifier stability and email best-effort behavior.

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 read-only identity retrieval tool, the description covers the purpose, usage, parameter semantics, and return behavior. It does not specify an output schema (none is provided) or error handling, but within the given scope it is fairly complete. The distinction from sibling tools (e.g., get_sessions_my) is implied through the emphasis on the end-user identity vs. session 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?

The description explains the role of auth.sessionToken (required, forwarded as Bearer) and connection.workspaceName/appId (defaults). It does not explicitly address body, query, or params, but these are likely unused for an identity endpoint per the schema. The schema itself provides descriptions for sessionToken, host, appId, and workspaceName, complementing the tool description. Overall, parameter usage is reasonably well documented.

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: it returns the workspace end-user's userId and email for the authenticated session token. It also specifies what it does not return (Firebase UID or session payload) and provides a concrete use case (correlation key for backend webhooks). This leaves no ambiguity about the tool's function.

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 gives explicit guidance on when to use this tool: 'Use it as the correlation key when your own backend needs to link an external event back to this user.' It also explains why not to use session token or session id for this purpose (they expire/rotate), which directly addresses alternative tool choices. This makes the usage conditions clear.

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