Get Phone Messages

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

Annotations already mark the tool as read-only and non-destructive, and the description adds meaningful behavior beyond that: the dual-mode behavior, the fact that navigate_to_tab will click the Messages tab first, and the return shape for each mode. It also warns that the contact name must match the UI exactly, which is valuable operational context.

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 a purpose line, two modes, Args, per-mode return shapes, and Tips. Each section serves a clear function, and the front-loaded purpose sentence immediately tells the agent what the tool does. The length is justified by the dual-mode complexity.

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 description provides return shapes for both modes, which matters because there is no output schema, and it gives practical lookup tips. However, the return shapes use '...' placeholders and the description does not cover failure cases such as a conversation name not being found or Phone Link not being connected, so it is strong but not fully complete.

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 the baseline is 3. The description adds a few genuinely useful nuances beyond the schema: the contact name must match what is displayed in the Phone Link UI, and max_messages applies to either conversations or messages depending on the mode. Most of the Args section repeats schema details, so it does not deserve a 5.

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 opens with 'Read SMS messages from Phone Link's Messages tab', a specific verb, resource, and UI location. It also defines two distinct modes, listing conversations vs reading a specific conversation, which clearly separates it from sibling tools like phonelink_get_calls or phonelink_get_photos.

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?

It gives explicit mode-level guidance: leave conversation_name empty to list conversations, provide a contact name to read that conversation, and 'Use list mode first to discover available conversations.' It does not explicitly compare this tool to sibling tools or state when not to use it, so it falls just short of full marks.

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