fitfly-engine

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It mentions the output voice ('Coach Fly's voice') and content type (coaching decisions), but does not disclose whether this is a read-only operation, how results are ordered, what the response format is, or whether it accepts pagination beyond the schema's limit parameter.

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 concise and front-loaded, using two sentences to convey purpose, content, and intended use. The parenthetical list efficiently clarifies what 'coaching decisions' means. It is not overwrought, though the title and first sentence overlap slightly in meaning.

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 simple tool with one optional parameter and no output schema, the description covers the core purpose and voice. It does not explain return structure or behavior of the limit parameter, but the tool is not complex enough to demand much more. Still, a brief note on the feed's contents or ordering would improve completeness.

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 schema has 0% description coverage and the description does not mention the 'limit' parameter at all. The parameter is optional and its name is somewhat self-explanatory, but the description adds no meaning about how it affects the returned feed (e.g., number of entries, default behavior).

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 clearly identifies the tool as the 'what changed & why' feed, explaining the engine's coaching decisions and giving concrete examples (volume bumps, deloads, swaps). This distinguishes it from sibling tools like get_program or get_todays_session, though it lacks an explicit verb like 'list' or 'retrieve'.

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 suggests a use case—'Use to explain to the athlete why their plan evolved'—which implies when to use it. However, it does not explicitly contrast with alternatives or state when not to use it, leaving the guidance somewhat implicit.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says "render-ready" which is ambiguous and does not state whether the tool is read-only, what it returns, or any side effects. The description does not reveal if the program is cached, if it errors when no program exists, or how the output should be consumed.

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 a single short fragment, which is concise in length, but it under-specifies. It does add the 'render-ready' detail beyond the title, but it is not a well-formed sentence and reads more like a label than an explanation. It is not as degenerate as 'Process', but it is still minimal.

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 tool's simplicity (zero parameters, no output schema), the description could be sufficient if it clearly explained the return value. It says "current multi-day program (render-ready)" which gives some sense that the output is a program object formatted for display. However, it does not explain what 'render-ready' means, what the structure is, or any edge cases. For a simple getter, this is adequate but not complete.

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 zero parameters, so schema_description_coverage is trivially 100%. There are no parameters to explain, and the description adds no parameter-related meaning. With 0 params, a baseline score of 4 is appropriate; there is nothing for the description to compensate for.

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 is a noun phrase: "The athlete's current multi-day program (render-ready)." It lacks an explicit verb like 'fetch' or 'list', though the name and title imply retrieval. It does add the scope 'multi-day' and the 'render-ready' qualifier, which distinguishes it somewhat from 'get_todays_session', but the purpose is still vague without a direct statement of action.

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?

There is no guidance on when to use this tool versus alternatives. The sibling tools include get_todays_session and regenerate_program, and the description does not mention any context such as 'Use this to retrieve the full program for rendering' or 'For today's session, use get_todays_session'. The lack of usage context leaves the agent to guess.

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

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

No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait: 'Auto-applies the user's readiness check-in (autoregulation) if they've done one today,' which tells the agent the returned workout may be adjusted based on readiness. However, it does not explicitly state whether the tool is read-only or if it has any side effects, leaving some ambiguity.

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, front-loaded with the core value proposition ('Today's workout: exercises, sets/reps...'). It avoids redundant phrasing and every sentence contributes useful information. It is efficient and well-structured.

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 there is no output schema and no annotations, the description provides a solid overview of what the tool returns: exercises, sets/reps, load guidance, target weights, nutrition targets, and cycle status. It also explains the auto-application of readiness. It does not cover edge cases like invalid dayIndex or error behavior, but for a simple retrieval tool, it is reasonably complete.

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 covers the only parameter (dayIndex) with a description, and schema description coverage is 100%. The tool description does not add any additional meaning about the parameter beyond what is already in the schema, so it meets the baseline but does not exceed it.

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 clearly states what the tool does: it returns today's workout details including exercises, sets/reps, load guidance, target weights, nutrition targets, and cycle status. The phrase 'Call this to see what the athlete should do now' gives a specific action and resource, and it implicitly distinguishes from sibling tools like get_program or nutrition_targets by focusing on the current daily session.

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 provides clear context for when to use the tool: when you need the athlete's current daily plan. It says 'Call this to see what the athlete should do now,' which establishes the primary use case. It does not explicitly list alternatives or exclusions, but the phrasing implies this is the go-to for today's session.

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

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

No annotations are provided, so the description carries the full burden. It discloses the filtering logic (same muscle group, equipment/level/injuries), which is valuable. However, it does not mention the return format, empty-result behavior, or invalid exerciseId handling, leaving some transparency gaps.

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?

Two short sentences: the first conveys the core purpose, the second gives usage guidance. No redundant words, and the most important information is front-loaded.

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 simple tool with one parameter and no output schema, the description provides sufficient context about what it does and when to use it. 'Valid alternatives' implies the return type. Minor gaps like exact return structure don't impede correct invocation.

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 schema has only exerciseId with no description, so the description must clarify its meaning. The phrase 'for an exercise' implicitly defines exerciseId as the target exercise. This adequately compensates for the 0% schema coverage given the single-parameter simplicity.

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 clearly states that the tool lists valid alternatives for an exercise, specifying same muscle group and filters by equipment/level/injuries. This distinguishes it from the sibling swap_exercise, which performs the swap. The title reinforces the purpose.

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?

Explicitly states 'Use before swap_exercise,' telling the agent exactly when to call this tool relative to its sibling. This is a clear workflow directive. The description also implies this is a prerequisite, which is sufficient guidance.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses that the engine runs progression logic (double-progression, e1RM), detects PRs, returns per-exercise outcomes, and provides next-time targets, plus kg units. This is substantial and goes beyond a simple 'log' statement.

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?

Three concise sentences: the first is the core purpose, the second explains the engine behavior and outputs, and the third clarifies units. Every sentence adds value and the main action is front-loaded.

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 moderately complex logging tool with no output schema, the description explains the key return data (per-exercise outcomes) and behavior (progression, PR detection). It omits semantic details about goal/dayIndex and any edge cases, but covers what an agent needs to make the call and understand the response.

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 33%, so the description must compensate. It adds important meaning: 'Weights are in kg' and 'completed sets' for the exercises array. However, it does not clarify goal or dayIndex semantics, leaving those under-specified. The schema provides enum/integer types but no real-world meaning.

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 phrase 'Record what the athlete actually lifted' gives a specific verb and resource, making it clear this is a write operation for logging completed workout sets. It distinguishes itself from read-oriented siblings like get_todays_session and get_program by focusing on recording actual performance.

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 implies when to use it: after the athlete finishes lifting, to log what was actually completed. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough for an agent to select this tool over read/session tools.

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

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: USDA truth-checking, feasible=false flag with notes for approximate macros, and a ~15s delay. This is substantial, though it does not mention side effects or required permissions.

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 a single concise sentence that front-loads the core purpose and adds critical behavior details (USDA check, feasibility flag, speed) without waste.

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?

While the description covers overall output behavior, it omits parameter semantics, usage context, and return structure. With no output schema and no annotations, this is insufficient for an agent to confidently invoke the tool 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 description coverage is 0%, and the description does not explain any of the four parameters (exclusions, mealsPerDay, trainingDay, dietaryStyle). The description fails to compensate for the lack of schema documentation.

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 clearly states the tool generates a day of meals hitting the athlete's targets, with unique details like USDA truth-checking and feasibility flags. This distinguishes it from sibling tools like nutrition_targets and workout-related tools.

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?

No explicit guidance on when to use this tool versus alternatives, no prerequisites or exclusions mentioned. The description focuses on behavior but does not contextualize selection among siblings.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It notes that targets are 'computed from body stats, activity, and goal,' implying a read-only calculation, but it does not explicitly state side-effect-free behavior, data freshness, or dependencies on user stats.

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 a single sentence that is front-loaded with the key output ('daily calorie + macro targets') and provides the computation source. No wasted words.

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 simple zero-parameter getter with no output schema, the description sufficiently conveys the return value and its derivation. It could mention the specific macro breakdown (e.g., protein, carbs, fat) but 'macro targets' is reasonably complete for typical use.

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 tool has zero parameters, so the baseline is 4. The description adds value by explaining what the computed targets represent, which is meaningful even though there is no schema to document.

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 clearly states the tool provides daily calorie and macro targets, with a specific verb 'Get' in the title and a clear resource. It distinguishes itself from siblings like meal_plan by focusing on numeric targets rather than a meal plan.

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 implies usage when the athlete's nutrition targets are needed, but does not explicitly contrast with alternatives like meal_plan. There are no explicit when-not conditions or alternative tool references, making the guidance purely implied.

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

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

With no annotations, the description carries the full burden. It discloses the three inputs, the readiness scoring, the workout reshaping (reduce volume/intensity/recovery day), and the return value (score + modifier). It does not mention idempotency or repeated submissions, but the principal side effects are transparent.

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 two sentences: the first states the purpose and inputs, the second covers scoring, downstream effects, and return value. Every word 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?

The tool is simple with 3 required integer parameters. The description covers input, behavior, side effects, and return value. Given the full schema and the clear linkage to get_todays_session, this is complete.

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 schema already describes each parameter's meaning and range (1-5), so the description's 'each 1-5' adds nothing new. The mention of readiness scoring provides some context, but the parameter semantics are otherwise fully covered by the 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?

The description opens with the verb 'Record' and resource 'readiness check-in' while specifying the three data points (energy, sleep, soreness). It clearly differentiates from siblings like log_workout and get_todays_session by stating its unique effect on the next session.

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 context is explicit: use it to record how the athlete feels today, and the description explains how it impacts the next get_todays_session. It stops short of naming alternatives or stating when not to use it, but the intended usage is clear.

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

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

With no annotations provided, the description carries the full burden. It discloses the action (rebuild whole program), the data source (stored profile), and latency (~20s AI generation). However, it does not warn about potential data loss or reversibility, and lacks detail on side effects such as whether the previous program is overwritten or whether a changelog is created.

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?

Two sentences with no filler. The first sentence states the action and source, the second gives usage guidance. Every clause earns its place, and the structure is front-loaded with the primary action.

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 zero-parameter tool, the description provides sufficient context: action, source, latency, and when to use it. It does not describe the return value, but no output schema exists, and the material facts are covered. The description is complete enough for an agent to know when and why to invoke this tool.

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 tool has zero parameters, and the input schema is empty with 100% schema coverage. The description adds no parameter-specific information, but none is required given the absence of parameters. Baseline 4 is appropriate.

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 uses the specific verb 'Rebuild' and identifies the resource as 'the whole program' from 'the stored profile', clearly distinguishing it from sibling tools like get_program or log_workout. The purpose is unambiguous and directly tied to the tool name.

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?

Explicitly states 'Use after a profile change or a plateau', providing clear trigger conditions for when to invoke this tool. However, it does not name alternative tools or specify when not to use it, so it lacks exclusions but still offers clear context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly reveals that the new lift starts fresh with day-one calibration, which is a non-obvious side effect. It also clarifies the meaning of scope. It does not mention reversibility or impact on existing history, but the key behavioral trait is disclosed.

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 two sentences, front-loaded with the main action and followed by essential scope semantics. Every sentence earns its place with zero fluff.

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?

The description covers the main purpose and scope behavior, and the calibration reset is an important detail. However, since there is no output schema, the description does not need to explain return values, but the 'dayIndex' parameter remains unaddressed, which is a gap for a tool with program-level mutations.

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 'scope' has a schema description). The description adds meaning for 'scope' by explaining today vs. program, and implies 'toExerciseId' must be a valid same-area alternative. However, the 'dayIndex' parameter is completely unexplained, and the IDs are not elaborated beyond their obvious nature.

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 clearly states 'Replace an exercise with a valid same-area alternative', which is a specific verb+resource. It distinguishes itself from sibling tool 'list_swap_options' by focusing on the action of replacement rather than listing options.

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 explains the two scope values ('today' = just this session; 'program' = going forward), providing clear context for when each should be used. However, it does not explicitly mention alternatives or exclusions, such as 'use list_swap_options first to see valid alternatives'.

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