get_progress

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

Annotations only cover the read-only safety profile; the description adds the matching algorithm (within a day either side, roughly the planned duration) and the rationale (shifted sessions still count as a good week), which is the key behavioral surprise. It also discloses the rendering side effect — an interactive plan card is drawn and calling again re-draws it — that no annotation conveys.

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?

Front-loaded with the core answer, then eligibility rules, then usage routing — structure is good. Slight redundancy in 'Read those back when something looks wrong: a mismatch is visible there rather than hidden' and in restating the card-drawing consequence twice, which costs a bit of tightness.

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 an output schema present, return values need not be enumerated, yet the description still flags the per-session plain-English reason field and points to get_activity_details for intensity. Combined with the card-rendering caveat and the sibling routing, an agent has everything needed to call and re-call it correctly.

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% (the single 'weeks' property has no description, minimum, or maximum), so the description carries the full burden and does: 'How many weeks back to report, including this one (1-12)' supplies both the inclusive-count semantics and the valid range that the schema omits.

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 opening line states a precise verb+resource: which planned sessions were completed, aggregated week by week. It explicitly separates itself from get_plan (plan overview) and get_activity_details (intensity assessment), so an agent can pick it out of a 25-tool family without opening a schema.

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 explicit when-to-use ('am I keeping up'), when-not-to ('For "how is my plan going", get_plan is the better first call'), and a re-fetch rule ('fetch it fresh only when a session may have been done since'). Alternatives are named and the condition that selects each is stated.

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