mcp-server-fatsecret

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Each tool targets a distinct resource or action, and descriptions are detailed, but the many prepare_* variants plus the commit tools and the escape hatch create mild potential for misselection, especially for new agents.
Naming Consistency5/5
All tools use the fatsecret_ prefix with snake_case verb_noun names; the prepare/commit pattern is consistently applied, and verbs (search, get, pick, start, complete, commit) are clear and uniform.
Tool Count2/5
28 tools is well above the 25-tool threshold, and while the domain is complex, the large number of near-parallel prepare_* operations makes the surface feel bloated.
Completeness4/5
The set covers auth, food/recipe search, diary entries (food, weight, exercise), saved meals, favorites, and profile, plus a read-only escape hatch. Minor gaps exist (e.g., no direct single-entry getter, no favorites list on Basic tier), but core workflows are covered.
Average 3.7/5 across 28 of 28 tools scored. Lowest: 2.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 3 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, but the description adds no behavioral context beyond those hints. It does not explain what 'profile status' entails, whether authentication is required, or what kind of data will be returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but under-specified. The single sentence does not meaningfully earn its place because it merely restates the tool's name without providing actionable detail, similar to the low-scoring 'Process' example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description should clarify the return payload. 'Your FatSecret profile status' is vague and ambiguous, especially alongside sibling tools like fatsecret_check_auth_status, leaving the agent uncertain about the tool's actual result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description has little to add. Per the rubric, a tool with no parameters receives a baseline score of 4, and the description does not present any conflicting or confusing parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Your FatSecret profile status' is a noun phrase that loosely paraphrases the tool's name without a clear verb like 'retrieves' or 'returns'. It fails to distinguish the tool from sibling tools such as fatsecret_check_auth_status, which also relates to account status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, typical use cases, or exclusions, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims 'dry-run', which typically implies no side effects, while annotations say readOnlyHint=false and idempotentHint=false, suggesting the tool may modify state (e.g., creating a prepared operation). This is a direct contradiction. The description also does not clarify what 'prepare' actually does, such as whether it stores an operation handle or merely validates input.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse, which harms its usefulness rather than helping. It is a single sentence without any structure to guide the agent on workflow, parameters, or return values. While brevity is good, the under-specification makes it insufficient for a tool with this complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters, a freeform nested object, and no output schema, but the description provides no context about what the tool returns, how to construct valid params, or how it relates to commit_prepared_operation. This is wholly inadequate for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameter meaning. It only paraphrases the method enum ('create/edit/delete') without elaborating on the `params` object structure, the `reason` field, or how parameters differ across methods. The schema provides no descriptions, and the description offers no compensation, leaving the agent to guess the required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Dry-run: create/edit/delete a saved-meal template'), giving a clear verb and resource. It distinguishes itself from sibling prepare tools by targeting saved-meal operations specifically, though it does not explicitly mention the two-phase prepare/commit pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like commit_prepared_operation or other prepare_* tools. The term 'dry-run' implicitly suggests a validation step, but the description does not explain the intended workflow or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Dry-run', implying the operation is non-destructive, but the annotations declare destructiveHint=true. This is a direct contradiction, as a dry-run suggests no actual deletion occurs, while the annotation indicates destructive behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but it omits critical details. While it does not waste words, it is under-specified, which reduces its usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema, has undocumented parameters, and the prepare/commit pattern is not explained. The description is too sparse to provide adequate context for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage and the description does not mention any parameters. It does not compensate for the lack of parameter documentation, leaving foodEntryId and reason completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('prepare deleting') and the resource ('a food diary entry'), and the 'Dry-run' prefix indicates a non-destructive preview. It distinguishes itself from sibling prepare tools (create, edit, copy) by specifying the delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool vs alternatives. It does not mention the prepare/commit pattern or any other context, leaving the user to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Dry-run,' which suggests no side effects, but the annotations indicate readOnlyHint=false, implying the tool may write (e.g., create a prepared operation). The description does not clarify the lifecycle (e.g., returning a prepared operation token required for later commit) or any other behavioral traits beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, but it is under-specified for a tool with 5 parameters and a prepare/commit pattern. It is front-loaded but far too brief to be fully useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is part of a prepare/commit workflow (evidenced by sibling tools), but the description does not explain the return value, the need to call commit_prepared_operation afterwards, or how parameters are used. With no output schema and minimal description, the context is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no information about the five required parameters. The parameter names (foodEntryId, servingId, numberOfUnits, meal, reason) are self-descriptive but the purpose of 'reason' and how parameters relate to the edit operation are not explained, leaving significant ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action: 'prepare editing an existing food diary entry.' This clearly distinguishes it from create/delete/prepare operations for other resources, and the 'Dry-run' prefix signals this is the preparation step, not the final commit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Dry-run' label implies this tool is used to validate or prepare an edit before committing, but it does not explicitly state when to use it versus alternatives like commit_prepared_operation or prepare_food_entry_create. The usage context is implied rather than directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it is a dry-run, a behavioral trait not in annotations. However, with readOnlyHint=false and openWorldHint=true, the term 'dry-run' is ambiguous regarding side effects. It does not explain whether a prepared operation is created or what other side effects may occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, front-loading the 'dry-run' concept. It is efficient, though the brevity sacrifices detail needed for full understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested parameters and no output schema, the description is too minimal to guide correct use. It does not explain the prepare/commit workflow, required fields for the params object, or what the response will contain, making it incomplete for a complex operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the three parameters (method, params, reason) beyond the schema. With 0% schema description coverage, it fails to compensate, leaving the agent without guidance on constructing valid inputs for this operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a dry-run for adding, editing, or removing a food inside a saved meal. It specifies the exact verb and resource, and the 'item' distinction differentiates it from sibling tools like fatsecret_prepare_saved_meal_operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'dry-run' label implies this is for preflight validation before actual changes, but the description does not explicitly state when to use this over alternatives or how it fits with the commit_prepared_operation flow. No exclusions or alternative tools are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the content scope (ingredients/directions/nutrition) but doesn't disclose any additional behavioral traits like response structure, pagination, or auth requirements beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the main content (full ingredients/directions/nutrition) and scope (for one recipe by id). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with one parameter and rich annotations, the description covers the essential: what is returned and how to identify the recipe. It is complete enough for an agent to select and invoke the tool, though it could mention where the recipe ID comes from.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for parameter meaning. The phrase 'by id' maps to recipeId, but since the schema already names the parameter 'recipeId' and defines it as a string with minLength 1, the description adds minimal extra value beyond restating the obvious. No format or source guidance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full recipe details (ingredients, directions, nutrition) for a single recipe identified by id. It distinguishes from sibling search tools by emphasizing 'for one recipe by id', but does not explicitly name alternatives like fatsecret_search_recipes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The description implies use when you have a recipe ID and need complete details, but it does not mention needing prior search to obtain the ID or contrast with other recipe-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description calls this a 'Dry-run' which typically implies no side effects, while annotations state readOnlyHint=false, indicating writes may occur. This is a direct contradiction, earning a score of 1.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that front-load the core purpose and key constraints without wasted words. It is well-structured and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and the existence of a commit workflow (siblings include commit_prepared_operation), the description is incomplete. It does not explain what 'prepare' returns, how it connects to a later commit, or the full parameter set, especially given the misleading dry-run annotation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains currentWeightKg (kg), firstTimeSetup (only on first weigh-in), and date (via backdate limit). However, it omits reason, comment, and does not clarify currentHeightCm or goalWeightKg beyond the minimal schema ranges, leaving several parameters underdefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it prepares logging current weight in kg, with specific constraints that distinguish it from other prepare_* siblings (height/goal-weight only on first weigh-in, backdate limit). The verb 'prepare' and resource 'logging your current weight' are concrete and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context that this is a dry-run preparation step and gives explicit usage constraints: pass firstTimeSetup=true only on the first weigh-in, and cannot backdate more than 2 days. However, it does not explicitly contrast with commit tools or other prepare tools, so alternatives are not named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds minimal context (emphasizing 'YOUR' account) but does not disclose any additional behavioral traits such as return format or that no authentication is required for the check.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, highly concise with no wasted words. It is appropriately sized for a trivial status-check tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 params, no output schema, basic read-only check), the description is mostly complete. However, it does not explicitly state what the tool returns (e.g., a boolean), which would be helpful for an agent, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. There is no need for parameter explanation, and the description correctly implies no inputs are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Whether YOUR FatSecret account is linked' clearly indicates the tool checks the linked status of the user's account. It distinguishes from siblings like fatsecret_start_auth and fatsecret_disconnect by focusing on the current state, though it lacks an explicit verb like 'checks'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention using it before auth-dependent operations or contrast it with start_auth/complete_auth, leaving the agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the 'dry-run' concept, which helps clarify non-execution behavior. Annotations already indicate not read-only, so there is no contradiction. However, it does not disclose what 'prepare' actually does (e.g., persists a draft operation), any validation steps, or side effects like storing temporary data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, efficiently conveying the core action and modality. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters, no output schema, and is one of many prepare_* tools. The description does not explain the preparation workflow, how the result should be used, or the purpose of 'reason'. An agent would lack crucial context to know what to do after invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description has the burden of explaining parameters. It only mentions from/to dates, leaving 'reason' completely unexplained and 'meal' unaddressed. The description adds minimal value beyond the parameter names in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'prepare copying one day's food entries to another date' with the 'dry-run' qualifier. This distinguishes it from sibling tools like create/edit/delete and aligns with the 'prepare' prefix.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a preparation step before a copy, but explicitly saying 'dry-run' gives some usage context. However, it does not mention that this is a prerequisite for commit_prepared_operation, nor does it distinguish this from other prepare_* tools beyond the copy verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds the requirement that the full operation object, a restated confirmOperationHash, and a fresh idempotencyKey must be supplied. It does not disclose success/failure behavior, side effects beyond 'write', or any auth-specific details, so it adds only partial context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The first sentence states the core action, the second lists required inputs. Every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic workflow but omits details about return values, error cases, and the specific relationship to prepare_* tools. No output schema exists, so the agent has no idea what the commit response looks like. For a generic commit tool, it is minimally adequate but not fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions only cover idempotencyKey (33% coverage). The description compensates by explaining that operation must be the full object, confirmOperationHash must be restated (matching a prior value), and idempotencyKey must be fresh. This adds semantic meaning that the schema lacks for two of the three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Execute' and identifies the resource as 'previously prepared write', clearly distinguishing from the prepare_* siblings which create operations. It does not explicitly differentiate from fatsecret_commit_profile_create, a more specific commit tool, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'after the caller has reviewed it', implying this should be used after a prepare call and after the agent presents the operation to the user. It does not explicitly list alternatives or exclusions, such as pointing to commit_profile_create for profile operations, nor does it say when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds the conditional behavior of the optional parameter, but provides no additional context on response structure, errors, or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise (9 words) and front-loaded with the key concept, but it is a sentence fragment without a clear subject-verb structure. It earns its place with no filler, though it could be better structured as a proper sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description covers the essential behavior and parameter semantics. The ambiguity in the phrase 'with savedMealId' is a minor gap, but overall it is adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description is the only source of parameter meaning. It explains that savedMealId identifies a specific saved meal to return its foods, while omitting it returns all templates. This adds meaningful semantic value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly communicates the resource and its two modes: retrieving saved-meal templates or the foods within a specific meal via savedMealId. It distinguishes from siblings like get_food/get_recipe, but lacks an explicit verb, relying on the title's 'Get' to signal the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the conditional mention of savedMealId: without it, you get templates; with it, you get foods. However, there is no explicit guidance on when to use this tool vs alternatives like prepare_saved_meal_operation or get_food.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the 'public' constraint and keyword-based search, but does not disclose pagination behavior, rate limits, or return format. Given the annotations cover safety, the description provides some additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is concise and front-loaded with the core purpose, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with good annotations, the description is minimally viable: it states the core action and required parameter. However, it lacks guidance on optional parameters, pagination, and alternative tools, making it incomplete for robust agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only explains 'query' implicitly via 'by keyword', but leaves 'maxResults' and 'pageNumber' completely unexplained. The schema provides defaults and bounds but no semantic meaning, so the description is insufficient for fully understanding the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' with a specific resource 'the public recipe database by keyword'. This distinguishes it from sibling tools like 'fatsecret_search_foods' (search foods) and 'fatsecret_get_recipe' (get a specific recipe).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is for keyword searching, but it does not explicitly mention when to use this vs. alternatives like getting a specific recipe or searching foods. The context is clear but there are no exclusion criteria or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds key behavioral context beyond annotations: it is a dry-run (no actual favorite change), and it reveals tier-based constraints for adding/removing vs. listing. Annotations already indicate readOnlyHint=false and destructiveHint=false, but 'Dry-run' is not captured by annotations. However, it does not explain the side effects of preparation (e.g., whether a prepared operation is stored) or the two-step commit flow, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with a concise parenthetical for tier information. Every word contributes value: 'Dry-run' sets expectation, 'mark/unmark' specifies the action, 'food or recipe' scopes the resource, and the tier note is practical. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a two-step 'prepare' flow (visible in sibling commit_prepared_operation), the description is incomplete. It does not explain how this tool relates to commit_prepared_operation, what output or state it produces, or how to populate the 'params' object. The dry-run and tier hints help, but the lack of param semantics and commit-flow context leaves significant gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter meanings. The 'method' enum is self-explanatory, but 'params' is an opaque generic object with no field guidance, and 'reason' is undefined. The description does not compensate for the schema's lack of documentation, so the agent would not know how to construct valid parameters (e.g., food_id, recipe_id).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's function: a dry-run to mark/unmark a food or recipe as a favorite. The verb 'mark/unmark' is specific to the favorite-change operation, and the scope (food or recipe) is clear. It distinguishes from sibling prepare_* tools by focusing on favorites, and the 'Dry-run' prefix clarifies it is a preparation step rather than a direct action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys when to use this tool via 'Dry-run' and the parenthetical about Basic/Premier tiers. However, it does not explicitly name alternatives (e.g., commit_prepared_operation) or state when not to use it. The tier information is a useful guide, but there is no direct comparison to other favorite-related tools or the commit step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it is an 'allowlisted escape hatch' and that mutating methods are rejected, implying a guardrail. This enhances transparency without redundancy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and every word earns its place. The exclusions and alternative guidance are packed efficiently without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is an escape hatch with generic parameters and no output schema, the description is adequate for selection (when to use) but incomplete for invocation. It fails to explain parameter semantics, expected return value, or error behavior. The strong annotations cover safety, but the missing parameter guidance is a significant gap for a tool meant to call arbitrary methods.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter details. The schema only lists methodId (string) and params (object), but does not explain what methodId should be (e.g., FatSecret API method name), how params should map to query parameters, or any format/constraints. The description's mention of 'GET methods' gives a minor hint, but it is far from sufficient for an agent to correctly invoke this escape hatch.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: an 'escape hatch' for read-only (GET) FatSecret methods not covered by a dedicated tool. It uses a specific verb ('call'), specifies the resource (FatSecret methods), and explicitly distinguishes itself from sibling tools by noting it covers methods without a dedicated tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: for read-only GET methods not covered by a dedicated tool. It also gives a clear exclusion: 'Mutating methods are rejected,' and directs users to the 'prepare/commit tools instead.' This is strong alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and idempotentHint=false, so the description is not expected to restate those. It adds the procedural detail about the PIN from fatsecret_start_auth, which is useful. However, it does not disclose side effects (e.g., token creation), error cases, or what happens if no auth flow is active. This is acceptable given the annotation hints but leaves some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the key action ('Finish linking') and includes the necessary context (PIN source). No extraneous words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one param) but lacks an output schema. The description covers the core usage but does not explain expected return values, error conditions, or the broader OAuth flow (e.g., that this is required for subsequent authenticated calls). Given the sibling tools provide flow context, it is minimally complete but not fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as the only parameter 'verifier' is fully described in the schema. The description repeats the same semantic ('PIN FatSecret showed you') without adding new meaning beyond the schema. Baseline score of 3 is appropriate because the schema carries the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: finishing the FatSecret account linking process using a PIN. It names the specific verb 'Finish linking' and resource 'FatSecret account', and distinguishes itself from siblings like fatsecret_start_auth and fatsecret_check_auth_status by referring to the PIN shown after the start step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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: after fatsecret_start_auth, when the user has received a PIN. It implicitly differentiates from alternatives by anchoring to a prerequisite step, but it does not explicitly state when not to use it or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a usage recommendation but no additional behavioral details such as return format or side effects. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences that state the purpose and usage guidance. There is no redundant phrasing or filler; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple discovery tool with strong annotations and optional parameters, the description provides enough context for an agent to use it correctly. It lacks details about the response format, but given no output schema and the tool's straightforward role, it is reasonably complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not mention 'query' or 'limit'. While the parameter names are somewhat self-explanatory, the description provides no explicit semantics, leaving the agent to infer what query string to pass and how limit controls results. With zero coverage, the description must compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb and resource: 'Find the right FatSecret tool/method'. This distinguishes it from the long list of sibling tools, which are all specific operations rather than a discovery/search tool. It is immediately obvious what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use first if unsure what is available' gives explicit guidance on when to invoke this tool, positioning it as the primary entry point for capability discovery. It does not discuss when not to use it or name specific alternatives, but the instruction is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, but the description clarifies that this is a dry-run and 'Nothing is written until commit confirms' – adding crucial behavioral nuance beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the key 'Dry-run' label, with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the prepare/commit workflow and non-writing behavior, but with no output schema and minimal parameter guidance, the agent may struggle to correctly fill all required fields. It does not explain what the prepared operation should return for commit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for 7 parameters, and the description only elaborates on servingId ('use fatsecret_pick_serving first to get servingId'). Other parameters like foodEntryName, numberOfUnits, meal, and reason rely solely on schema types/names, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Dry-run: prepare logging a food into your diary', which clearly states the verb+resource. It distinguishes from edit/delete siblings by explicitly targeting creation and referencing the prerequisite pick_serving step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It instructs the agent to use fatsecret_pick_serving first to obtain servingId, and states that nothing is written until fatsecret_commit_prepared_operation confirms. This provides clear workflow context, though it does not explicitly exclude edit/delete scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context by revealing the 'fuzzy-matches' behavior and natural-language parsing, which are traits not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action and purpose without waste. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives context for the use case ('before logging it') but omits critical runtime behavior: what happens when no serving matches, or whether it returns the matched serving object or an ID. Since there is no output schema, the description should clarify these aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the burden. It implicitly maps 'food's servings' to foodId and 'natural-language quantity' to quantityDescription, but does not explain the meaning of the default empty string or what happens if quantityDescription is omitted. This is partial but not complete compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: fuzzy-matching a natural-language quantity against a food's servings. It also explains the benefit (avoiding manual inspection of the servings array), which distinguishes it from sibling tools like getting a food's details or preparing an entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it ('before logging it') and provides context about the workflow. However, it does not explicitly mention alternatives or exclude cases where it should not be used, such as when an exact serving ID is already known.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnly=false, destructiveHint=true, and idempotentHint=false. The description adds useful behavioral context: it is a restricted fallback auth path gated by an environment variable and intended only for dev/test, not real accounts. It does not cover side effects in detail, but the annotations plus this context are sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The first sentence states the action and scope, the second gives the prerequisite and preferred alternatives. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage restrictions, and alternatives, which is strong. However, it lacks any explanation of the required operation and confirmOperationHash fields, and there is no output schema. For a fallback commit tool with nested objects, this leaves a meaningful gap in operational completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%: only idempotencyKey has a description. The main description adds no parameter guidance, leaving operation and confirmOperationHash completely unexplained. With low schema coverage and no compensating explanation in the description, the agent lacks clarity on required inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Executes ONLY the profile.create fallback auth path.' It names the exact resource/function and scopes it as a fallback dev/test path, which also distinguishes it from sibling auth tools like fatsecret_start_auth and fatsecret_complete_auth.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (fallback auth path only), the prerequisite environment variable ('Requires FATSECRET_ENABLE_PROFILE_CREATE=true'), and directs users to prefer fatsecret_start_auth/fatsecret_complete_auth for real accounts. This provides clear usage boundaries and named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the monthSummary behavior and the date scope, but does not disclose response structure or edge cases. With annotations providing a solid baseline, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the core function and the key variant. No wasted words; every part contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two parameters and no output schema, the description plus annotations provide sufficient context. It lacks details on the exact entry fields or auth requirements, but the title and sibling context fill most gaps. A small gap remains regarding what a monthly summary entails, hence a 4 rather than 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so by explaining the 'date' parameter (one date) and 'monthSummary' (true for a whole month), directly linking the parameter semantics to the function's behavior. This adds meaning beyond the raw schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource ('food diary entries') and the operation ('get'), with the scope options of one date or a whole month. It distinguishes from sibling tools by explicitly targeting food diary data, unlike weight, exercise, or recipe tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 (for a specific date or month via monthSummary), but does not explicitly mention alternatives or when not to use it. The sibling list implies it is for food diary reads, but no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag it as destructive (destructiveHint=true, readOnly=false). The description adds valuable context by specifying exactly what is destroyed (stored FatSecret tokens) and where (this server), clarifying the scope of the operation. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that immediately communicates the action and target. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description fully covers what the tool does and its scope. The destructive nature is reinforced by annotations, so no further detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially fully covered. The description correctly avoids adding unnecessary parameter details. Baseline 4 for no parameters is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and identifies the resource ('your stored FatSecret tokens from this server'). This clearly distinguishes it from sibling auth tools like start_auth/complete_auth, which are about establishing connections, not removing them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is clear enough that when to use it is implied (when you want to revoke stored FatSecret credentials), but it doesn't explicitly state alternatives or exclusion conditions, such as 'use check_auth_status to verify before disconnecting' or 'this does not revoke tokens on FatSecret's side'. Without explicit guidance, it relies on the reader's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (read-only, idempotent, non-destructive), so the description's role is lighter. The description adds context about the return content (nutrition detail + servings) but doesn't disclose additional behavior like error cases or auth requirements, which is acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one compact sentence with no filler. It front-loads the key outcome (full nutrition detail + servings) and the source context in a readable way.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description covers purpose, source, and output scope. It doesn't need to discuss return formatting or errors since annotations and schema handle safety and required parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema only declares foodId as a string; the description fills in the semantic gap by identifying it as an ID from fatsecret_search_foods, which is critical for avoiding confusion with other ID-based tools. This adds meaningful meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full nutrition detail and servings for a specific food ID. The phrase 'from fatsecret_search_foods' differentiates it from search and entry tools, making the purpose explicit and tied to a clear input source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after fatsecret_search_foods to obtain the food ID. It doesn't explicitly list when not to use it or alternative tools, but the source hint provides sufficient context for selecting it over sibling tools like get_food_entries or get_recipe.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the month-scoping behavior and that it returns 'your' history (scoped to authenticated user). It does not describe return fields or pagination, so with annotations covering the safety profile, 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence (7 words) that directly states purpose and key constraint. It is well-front-loaded with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and no output schema. The description covers the purpose and parameter semantics, but does not explicitly state the response structure. Given low complexity and strong annotations, it is adequate but could be slightly more explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'date' with no description (0% coverage). The description defines the parameter as the anchor date for a month of history, which is essential semantic information not present in the schema. This fully compensates for the lack of schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action: it retrieves the user's weight history. It specifies a time scope ('for a month containing the given date'), which differentiates it from sibling tools like fatsecret_get_food_entries or fatsecret_get_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: when you need a month of weight history for a specific date. It does not explicitly name alternatives, but the context is unambiguous. No exclusions are given, so 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters2/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals the dry-run nature (preparation, not execution) and the specific FatSecret API constraints (template save, day commit, entry edit). It adds context about what operations are possible and what 'edit' does (shifting minutes). This goes beyond the annotations (readOnlyHint=false, etc.) and clarifies the tool's non-executing, preparatory behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, front-loaded with the core purpose, and every sentence adds value: purpose, operation options, and alternative. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides strong context about the tool's purpose and alternatives, but omits the critical follow-up step of committing the prepared operation (e.g., fatsecret_commit_prepared_operation) and does not describe the parameter structure for each method. Given the tool's complexity (3 methods, free-form params, no output schema), this leaves gaps for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description carries the full burden for parameter semantics, but it fails to explain the 'params' or 'reason' parameters. It only names the method enum values without detailing the parameters required for each method, leaving the free-form params object entirely opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Dry-run: prepare an exercise-diary write,' identifying the exact purpose and scope. It enumerates the three supported methods and explicitly distinguishes the tool from fatsecret_log_one_off_exercise, making its function unambiguous relative to sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: it states that FatSecret has no ad-hoc single-workout create, lists the three applicable methods, and directly instructs to use fatsecret_log_one_off_exercise for one-off workouts. This clearly defines when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: each result's food_description carries calories/macros, and the database is US-only on the free tier. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, result format/reference, and a critical limitation with workaround. Front-loaded and no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema, the description explains the key return content (food_description with calories/macros) and a critical limitation. It is complete enough for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'query' via 'search by keyword', but does not mention maxResults or pageNumber. These are somewhat self-explanatory from names and constraints, so a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches FatSecret's public food database by keyword, which is a specific verb+resource. It distinguishes from sibling tools like fatsecret_search_recipes (recipes vs food) and fatsecret_get_food (structured data vs search results).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs to use fatsecret_get_food for structured serving data, and provides a detailed NOTE about the US-only limitation on the free Basic tier with a workaround for Danish foods. This gives clear when-to-use and alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly=false, idempotent=false), the description discloses the multi-step nature: returns an authorize URL, requires the user to log in and approve, and yields a PIN. This gives valuable behavioral context that the annotations alone don't convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and every sentence adds essential flow information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 0-parameter auth-start tool with no output schema, the description fully covers the workflow, including the user's actions and the exact next step (fatsecret_complete_auth). It is sufficiently complete for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially complete. The description adds no parameter details, but none are needed; baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Start linking') and identifies the resource ('YOUR real fatsecret.com account'). It clearly differentiates from siblings like fatsecret_complete_auth and fatsecret_check_auth_status by outlining the initial step of the OAuth flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the intended use: to initiate linking a real FatSecret account and explicitly directs the user to pass the resulting PIN to fatsecret_complete_auth. This provides clear context and a named next step, though it doesn't explicitly state exclusions (e.g., when already authenticated).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds behavioral details about the monthSummary and includeTypes flags, which are not conveyed by annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, immediately identifying the primary purpose and optional modes. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with strong annotations and simple parameters, the description covers all invocation modes and return variations. No output schema is present, but the description sufficiently informs selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero schema description coverage, the description explains all three parameters: date (implied by 'for one date'), monthSummary (switch to month summary), and includeTypes (list known exercise types). This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves exercise diary entries for a specified date, with options for month summary and exercise types. It distinguishes itself from sibling tools like fatsecret_get_food_entries by explicitly mentioning 'exercise'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 this tool – retrieving exercise diary data for a date or month, or listing exercise types. It does not explicitly name alternatives or exclusions, but the resource is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mcp-server-fatsecret MCP server](https://glama.ai/mcp/servers/borgels/mcp-server-fatsecret/badges/card.svg)](https://glama.ai/mcp/servers/borgels/mcp-server-fatsecret)

Score Badge

Copy to your README.md:

[![mcp-server-fatsecret MCP server](https://glama.ai/mcp/servers/borgels/mcp-server-fatsecret/badges/score.svg)](https://glama.ai/mcp/servers/borgels/mcp-server-fatsecret)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/borgels/mcp-server-fatsecret'

If you have feedback or need assistance with the MCP directory API, please join our Discord server