list_announcements

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without the description. The description does add real behavioral value by disclosing the effective default time windows (14 days back, 28 days forward), which are not visible in the schema where both dates default to null. It says nothing about pagination, result ordering, or how many courses can be batched per call.

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?

Purpose is front-loaded in the first sentence, followed by a compact Args block with one line per parameter and no filler. The docstring-style Args formatting is slightly redundant with the schema keys but is dense rather than wasteful.

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?

An output schema exists, so return-value explanation is not required, and the date defaults make the temporal window usable. For a multi-course listing call, however, it omits what an agent still needs: whether the date filter is on posting date, any cap on course_ids length or pagination behavior, and timezone handling for the YYYY-MM-DD bounds.

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% and the schema types are untyped strings with null defaults, so the description carries the full burden — and it does: it states the date format (YYYY-MM-DD) and, critically, the actual effective defaults (14 days ago / 28 days forward) that contradict the null defaults in the schema. It does not clarify whether start_date applies to posting date, timezone, or what happens if only one bound is supplied.

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?

"List announcements across one or more courses" gives a specific verb and resource plus the batching scope (multiple courses at once), which is exactly the detail an agent needs. It stops short of distinguishing itself from nearby read tools such as list_discussions or whats_new, so it is clear but not sibling-differentiated.

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?

There is no guidance on when to choose this tool over the many other read/feed tools in the namespace (list_discussions, activity_stream, whats_new, list_inbox). The usage is only implied by the tool name and the phrase "across one or more courses"; no exclusions, prerequisites, or alternative routing are stated.

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