Log a One-Off Exercise (FatSecret)

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

The description goes well beyond the annotations by detailing the exact side effects: the current template is saved, overwritten, and restored; the operation spans three separate API calls without atomicity; and the tool performs best-effort restore with a suggested verification step. This provides the agent with a clear model of what mutates and what could go wrong, exceeding the basic readOnlyHint=false annotation.

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 three sentences long, and each sentence carries essential information: the orchestration flow, the failure behavior and non-atomicity, and the required environment variable. It is front-loaded with the core purpose and contains no filler.

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 complex tool with no output schema and only partial parameter documentation, the description is remarkably thorough: it explains the full workflow, the side effects, the lack of atomicity, and the recovery check. The only notable gaps are parameter semantics (scored separately) and an explicit statement of the success return value, though the recovery guidance implies the outcome.

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 only 25% (only idempotencyKey has inline documentation). The tool description mentions 'the given date' but does not explain exerciseId, minutes, or date format beyond what the schema already has. With such low schema coverage, the description should have compensated by explaining where exerciseId comes from or what minutes represents, but it does not.

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 begins with 'Orchestrates a one-off, never-to-repeat workout via FatSecret's template mechanism', which clearly specifies the verb, resource, and scope. The step-by-step explanation of saving/overwriting/restoring templates distinguishes it from sibling tools like fatsecret_prepare_exercise_operation and fatsecret_commit_prepared_operation.

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 clearly conveys the use case (one-off exercise logging) and the prerequisite FATSECRET_ENABLE_WRITES. It also suggests checking fatsecret_get_exercise_entries on failure, which is a useful recovery context. However, it does not explicitly contrast it with alternatives such as the prepare/commit pair, so it stops short of full when-to-use versus when-not-to-use guidance.

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