zulip

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

With no annotations provided, the description carries full burden and does well by explaining the tool's behavior: it describes the dual input modes, pagination capability via before_message_id, default/max values for num_messages, and auto-discovery feature. However, it doesn't mention rate limits, authentication needs, or error conditions.

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 and appropriately sized. It front-loads the core purpose, then explains usage modes clearly, followed by a parameter summary. Every sentence adds value with no redundancy or 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?

Given 5 parameters with 0% schema coverage and no annotations, the description does an excellent job explaining parameter relationships and usage. With an output schema present, it doesn't need to explain return values. However, it could mention authentication requirements or error handling for a read operation tool.

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%, so the description must compensate fully. It successfully adds meaning beyond the schema by explaining the relationships between parameters (stream/topic vs. message_id), the purpose of before_message_id for pagination, default/max values for num_messages, and the 'Both' scenario when all parameters are provided.

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's purpose with specific verbs ('Get messages', 'fetch context') and resources ('stream/topic', 'message ID'), distinguishing it from siblings like get_message_by_id (single message) and send_message (write operation). It explains the dual functionality of fetching from a topic or around a specific message.

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 usage guidance with the 'Accepts either...' section, detailing when to use stream+topic vs. message_id vs. both. It implicitly distinguishes from get_message_by_id (single message) and send_message (write), though it doesn't name alternatives directly.

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