vorion_tenant_whoami

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

With no annotations provided, the description carries the full burden. It discloses that the tool resolves the API key, returns specific fields (tenant id, role, capabilities), and requires the VORION_API_URL and VORION_API_KEY env vars. This adds meaningful context. It does not explicitly state whether it is read-only or describe error handling, but for a simple lookup tool this is adequate.

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-loaded with purpose and return values, followed by usage guidance and requirements. Every sentence adds value; 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?

The description covers the tool's purpose, when to use it, required environment variables, and return values (tenant id, role, capabilities). With no output schema, this is sufficient. It could add error scenarios or explicit read-only confirmation, but overall it is complete for the tool's simplicity.

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 input schema has zero parameters, so the baseline is 4. The description goes further by explaining that the tool uses the calling API key and requires specific environment variables, adding meaningful operational context beyond the empty schema.

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 resolves the calling API key against the Cognigate Runtime and returns the tenant id, role, and capabilities. It is specific and distinct from sibling tools like vorion_tenant_list, which lists tenants, whereas this tool identifies the current session's tenant context.

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 explicitly advises 'Use this first if you need to confirm which tenant context the MCP session is running in', giving a clear when-to-use scenario. However, it does not mention when not to use it or alternative tools, so it stops short of full alternatives coverage.

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