superchat_list_conversation_notes

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations: it clarifies that the notes are internal/team-visible (not customer messages), that the tool returns only one page (pagination is not automatic), and that Enterprise access is a prerequisite for the alternative message-history tool. The only minor gap is that it doesn't describe the shape of the returned page, but with no output schema and a pagination-focused description, the one-page behavior is the most important behavioral trait and it is disclosed.

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?

Two sentences with zero waste. The first sentence states the core action and scope ('List one page of internal notes attached to a conversation'), and the second sentence adds the critical distinction from customer messages plus the sibling tool name. Every clause earns its place, and the most important scoping information is front-loaded.

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, paginated list tool with 100% schema coverage and no output schema, the description is nearly complete. It covers the resource type, the team-visible nature, the one-page behavior, and the alternative for message history. The only missing context is what the returned page contains (e.g., note fields like author, timestamp, content), but since there is no output schema and the tool is a simple list operation, this is a minor gap rather than a critical omission.

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 100%, so the schema already documents all four parameters (conversation_id, after, before, limit) with types, constraints, and descriptions. The tool description adds no parameter-level detail beyond what the schema provides, but it does reinforce the pagination semantics by saying 'one page' and 'never fetches later pages automatically.' Baseline 3 is appropriate because the schema carries the full parameter documentation burden.

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 states a specific verb ('List'), a specific resource ('internal notes attached to a conversation'), and a scope ('one page'). It also distinguishes the tool from a sibling by clarifying these are team-visible internal notes, not customer messages, and explicitly names list_conversation_messages as the alternative for message history. This makes the tool's purpose unambiguous and differentiates it from the sibling list_conversations and get_conversation tools.

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 says when to use this tool (to list internal team-visible notes) and when not to use it (for customer message history, use list_conversation_messages when Enterprise access is enabled). It also names the alternative tool directly. This is clear routing guidance that an agent can act on without needing to inspect sibling schemas.

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