whoami

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

Beyond the readOnly/idempotent annotations, it discloses that the API secret is never returned and that view=status works before POSTERLY_API_KEY is configured — a genuinely useful behavioral trait an agent could not infer elsewhere. It also states what to do when onboarding.completed is false, which shapes agent behavior in a way annotations cannot.

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?

Front-loaded with the identity answer, then the status view, then the session-level directive; every clause carries information. The onboarding walkthrough is a long parenthetical and borders on procedural bloat for what is still fundamentally an inspection tool.

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 no output schema and only two optional enum parameters, the description fully carries the burden by enumerating returned fields for both views and flagging the secret-exclusion guarantee. Nothing material is missing for an agent to call it correctly.

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 baseline is 3, but the description adds real meaning: it spells out the fields returned per view and expands include=api_keys into name, prefix, scopes, created, last used. It stops short of adding syntax or format detail beyond the enum semantics.

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?

Names the resource concretely ('Who you are and how posterly is connected') and enumerates exactly what each view returns (authenticated user, API key scopes, workspaces, onboarding next step). It does not, however, distinguish itself from the sibling posterly_status tool, which appears to overlap heavily with view=status.

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?

Explicitly prescribes 'ALWAYS call this at the start of a session' and explains when each view/include value applies, including that status works before the API key is configured. It gives no guidance on when to prefer the sibling posterly_status instead of view=status, leaving the main routing ambiguity unresolved.

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