update_course

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

Goes well beyond annotations by disclosing the read-modify-write pattern, that the WHOLE record is PUT back (so concurrent callers can clobber), that it throws before any request on invalid input, and that just-created courses may 429. This is exactly the behavioral detail annotations cannot convey.

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?

Dense and front-loaded: the mechanism leads, followed by concurrency, validation, and rate-limit notes in order of importance. The 2026-09-24 observation date is minor provenance padding, but every fragment otherwise earns its place.

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 mutation tool with no output schema, it covers behavior, failure modes, and concurrency adequately. It omits the response shape and auth requirements, but annotations cover the open-world/read-only profile, leaving only minor gaps.

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 only 50%, so the description must compensate. It does so by revealing that at least one of the two change fields must be supplied and that a blank name is rejected, adding real meaning about the nested 'changes' object beyond the raw schema.

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?

States a specific verb and resource (updates a course record) and describes the exact mechanism (GET, overlay, PUT back to /course-service/course/{courseId}). It distinguishes itself clearly from get_course/list_courses/create_course by being the write path, though it never names a sibling explicitly.

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?

Gives clear operating context: this is the same request Garmin's web editor sends on Save, and it notes the concurrency hazard and 429 condition. It does not explicitly route the agent between alternatives like update_workout or update_calendar_event, but the when-to-use context is solid.

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