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

The description adds behavioral context beyond annotations: it lists multiple actions (create, update, archive, unarchive) and notes that archiving is reversible, mentions bulk support, and gives specific guidance on retrieving IDs using other tools. However, it does not clarify how the tool selects an action (e.g., based on which parameters are provided) or disclose any side effects or permission requirements.

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 somewhat structured with a bullet list of actions and static options, but it is verbose and contains redundant statements (e.g., the first line repeats the actions list). The 'Flattened action: create_session' note is confusing and disrupts clarity. It could be more concise by focusing on the actual scope of this 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?

Given the zero schema coverage and no output schema, the description fails to provide sufficient context for a 26-parameter tool. It does not explain which parameters are required for each action, the expected data types beyond numeric codes, or the workflow order. While it references related tools for finding IDs, it lacks examples or a clear usage pattern, making it incomplete for the complexity.

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?

The input schema has 26 parameters with 0% description coverage. The description only explains static options for trainingType, goal, difficulty, and day, and briefly mentions how to get serie_id and exercise_session_id. The vast majority of parameters (reps, weight, rest, account, dates, etc.) are left unexplained, forcing the agent to guess their meaning and usage.

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 claims to 'Create / update workout routines, sessions, and exercises' but the tool name and '[Flattened action: create_session]' suggest it is specifically for creating sessions. This ambiguity is compounded by the existence of sibling tools like mfit_workout_write_create_routine and mfit_workout_write_add_exercise, which implies this tool may not be the correct choice for those actions. The purpose is vague and inconsistent.

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 mentions destructive operations should use mfit_workout_delete, but does not provide guidance on when to use this tool versus the other write siblings (e.g., mfit_workout_write_create_routine, mfit_workout_write_add_exercise). It seems to suggest this tool can handle all non-destructive writes, which may mislead the agent into using it for actions better served by more specific tools.

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