prepare_activity_publication

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

It adds real context the annotations do not carry: role permission required on the hosted service, a draft-without-reference fallback when EMOM rounds or achieved values are missing, duplicate notices, and the writeConfirmationPolicy split between bookingCreation and activityPublication. However, the closing paragraph instructs the caller to execute 'with confirmed: true' and to 'omit confirmed', yet no such parameter exists in this schema, so the execution semantics are muddled for a tool the annotations mark readOnlyHint=true.

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 first sentence is front-loaded and the display/verification sentences are compact, but the trailing confirmation-policy block is near-boilerplate, references a parameter that does not exist here, and doubles the length without adding callable guidance for this specific tool.

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 values need not be spelled out, and the description still covers permission requirements, the draft fallback, duplicate notices and confirmation policy. The remaining gaps are gymId and comment, plus the unresolved 'confirmed' instruction that belongs to the execute sibling.

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%, so the description must carry parameter meaning; it names source ID, activity date, difficulty variant and 'achieved results or actual loads' and clarifies that historical RM suggestions and prescribed rounds are not valid results. It never explains gymId or comment, and does not map 'audience' or 'WOD TV' to any actual parameter, leaving two of seven parameters undocumented anywhere.

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 sentence gives a specific verb and resource: 'Prepare one own activity entry from a current verified gym workout.' The 'Prepare' framing plus the sibling names prepare/execute activity_publication make the two-stage intent inferable, though the description never names execute_activity_publication 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?

It tells the agent what inputs to supply and how to treat historical RM suggestions and prescribed rounds, but the when-to-use routing is only implied by the word 'Prepare'; no sentence says 'call this first, then call execute_activity_publication'. The confirmation-policy paragraph gives conditional instructions but points at a 'confirmed: true' step rather than at the sibling tool.

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