session_enter

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

Adds meaningful behavioral context beyond the annotations: the tool registers the app/session pair, resolves human-vs-dispatch entry mode, and returns a specific orientation payload. With idempotentHint=true, readOnlyHint=false, and destructiveHint=false already declared, the description enriches the safety profile rather than just restating it. Re-entry behavior is not described, but the idempotent hint largely covers retry safety.

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?

Three front-loaded sentences with zero filler: the critical 'FIRST CALL' directive leads, the behavioral summary follows, and the closing-tool routing ends. The long enumeration of returned orientation items earns its place because there is no output schema to fall back on.

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 detailed orientation return list (project info, ORIENT.md, standing records, latest handoff, aliases, FRANK presence) compensates well for the missing output schema, and the close-session routing completes the lifecycle picture. Remaining gaps are minor: no prerequisites, error conditions, or re-entry semantics beyond what the idempotentHint implies.

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 description coverage is 0% across 5 parameters, so the description must compensate. It explains only dispatch_id ('pass dispatch_id when entering to work an assigned packet'), which is genuinely useful, but leaves app_id, session_id, project, and workspace without any added meaning beyond their bare names. Four of five parameters remain semantically thin.

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 a specific verb and resource — 'Registers the app/session pair, resolves the entry mode... and returns orientation' — with a clear scope. The opening 'FIRST CALL of any session' distinctly separates it from sibling session tools like session_read, session_bind, and session_reconcile. No ambiguity about what this tool does.

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?

Gives explicit positioning ('FIRST CALL of any session') and routes the agent to the appropriate complementary tools by path: 'session_handoff_write (human path) or handoff_write_v4 (dispatch path).' Also explains when to pass dispatch_id ('when entering to work an assigned packet'). Lacks an explicit 'when not to use' exclusion, but the lifecycle framing leaves little to inference.

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