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

With no annotations, the description carries full responsibility for behavioral disclosure. It explicitly says 'Create or replace a session' (indicating it may overwrite existing state) and clarifies that it initializes conversation state. It also explains that user_profile should only contain stable fields. While it doesn't disclose details like side effects on existing sessions or authorization requirements, the 'replace' wording and workflow guidance provide meaningful behavioral context beyond a simple action label.

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 well-structured with clear sections: PURPOSE, DO, DO NOT, CORRECT WORKFLOW, WRONG/RIGHT examples. Each section serves a purpose and the examples illustrate constraints effectively. It is longer than a minimal description, but the structured format and front-loaded purpose sentence make it easy to scan and use.

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?

Given 5 parameters and no annotations, the description covers the core workflow, constraints, and relationship to sibling tools. It explains when to call it, what to pass, and what to avoid. However, it omits any explanation of required session_id, user_id, or metadata, and doesn't mention return values. Since an output schema exists, return values need not be explained, but the missing parameter semantics leave some gaps in completeness.

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 0%, so the description must compensate. It adds meaning for user_profile and preferred_language, including explicit guidance that city, checkin_date, checkout_date, and search filters must not go into user_profile. However, it fails to explain the required session_id parameter or the purpose of user_id and metadata. This is a notable gap, though the description does provide meaningful semantics for the most complex parameters.

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 'Create or replace a session' and outlines its purpose to initialize conversation state and store stable user profile fields. This distinguishes it from sibling tools like clear_session, get_session_state, and update_user_profile, as it is the session initialization entry point.

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 provides explicit workflow instructions: 'call this before other hotel-related tools' and lists a correct sequence (start_session -> update_user_profile_from_model -> update_stay_dates -> search_hotels). It also gives DO and DO NOT lists, including exclusions for what should not be placed in user_profile (city, checkin_date, checkout_date, search filters), and demonstrates both wrong and right usage examples.

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