simplepractice_list_announcements

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

The readOnlyHint annotation already covers the read-only nature, and the description does not contradict it. The description adds behavioral context about the readAt field indicating read/unread status, which is useful. However, it does not disclose other behaviors like pagination (pageSize parameter), default ordering, or what happens when there are no announcements. Since annotations cover safety, the description adds some value but could be richer.

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 extremely concise, consisting of two short sentences. The first sentence states the core purpose, and the second adds a relevant detail about the readAt field. Both sentences earn their place with no fluff. Information is front-loaded, with the primary noun first. Ideal conciseness for the amount of content.

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?

With only one simple parameter and no output schema, the description provides enough to understand what the tool returns at a high level (announcements with readAt status). However, it does not explicitly state that the response is a list of announcements, nor does it mention pagination behavior or ordering. Since there is no output schema, the description could compensate by outlining the response structure more clearly. It is minimally complete but not fully self-sufficient.

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%, meaning the description does not explain any parameter. The only parameter, pageSize, is documented in the schema with type, default, and maximum, but the description adds no meaning about its effect (e.g., how to control result count). With low coverage, the description should compensate, but it remains silent on the parameter entirely. This is a gap in parameter explanation.

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 identifies the resource (announcements posted to the Client Portal) and adds a key semantic detail (readAt is null on unread ones), which differentiates it from other list tools like list_appointments or list_documents. The verb is implied by the name 'list_announcements' but the description reinforces the purpose. It is specific enough to distinguish from siblings, though it could explicitly state it returns a list.

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 no guidance on when to use this tool versus alternatives. There is no mention of scenarios, exclusions, or comparisons to sibling tools. While the name and description make it obvious it's for announcements, it does not address selection criteria or context, such as 'use this to fetch announcements for the portal' or 'do not use for appointment data.'

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