Skip to main content
Glama

upsert_and_log

Finds or creates a custom food by name and logs it for a meal in one step, preventing duplicate entries and separate search, create, and log calls.

Instructions

Find-or-create a custom food then log it in one step

    Searches the user's custom food library for food_name. If found, logs
    it immediately. If not found, creates it with the provided nutrition
    data and then logs it. This avoids duplicate food entries and removes
    the need for separate search → create → log round-trips.

    Matching is by food_name alone (case-insensitive) — brand_name never
    affects find-or-create lookup, so it can't cause a duplicate by missing
    an existing unbranded record. If an existing match is found, it is
    logged as stored, using its first serving: calories, carbs, protein,
    fat, brand_name, serving_unit and number_of_units are all ignored and
    the stored food is not changed; only serving_qty applies. Those values
    only take effect when creating a new food. To change an existing
    food's nutrition, serving size or brand, use update_custom_food.

    On an error after creation, custom_food_created is true and
    write_committed describes the food log, not the library food. A failed
    or exhausted lookup never triggers another create automatically.

    Args:
        meal_date: Date in YYYY-MM-DD format
        meal_time: Time in HH:MM:SS format (account timezone); used to
            determine the meal automatically
        food_name: Name of the food to find or create
        calories: Calories per serving (new food only)
        carbs: Carbohydrates in grams per serving (new food only)
        protein: Protein in grams per serving (new food only)
        fat: Total fat in grams per serving (new food only)
        brand_name: Brand or vendor name (new food only)
        serving_unit: Unit for serving size (e.g. "G", "ML", "OZ"). Default "G"
            (new food only)
        number_of_units: Serving size in the specified unit. Default 100
            (new food only)
        serving_qty: Number of servings to log (default 1)
    

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "meal_date": "<meal_date>",
      "meal_time": "<meal_time>",
      "food_name": "<food_name>",
      "calories": "<calories>"
    },
    "name": "upsert_and_log"
  }
}

Input Schema

NameRequiredDescriptionDefault
fatNo
carbsNo
proteinNo
caloriesYes
food_nameYes
meal_dateYes
meal_timeYes
brand_nameNo
serving_qtyNo
serving_unitNoG
number_of_unitsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare the generic write profile (readOnly=false, destructive=false, idempotent=false, openWorld=true); the description goes far beyond by disclosing that matching is case-insensitive on food_name only, that brand_name never affects lookup, that stored values are not mutated on a match, and that on a post-creation error custom_food_created is true while write_committed refers to the log entry. It also states that a failed lookup never auto-retries a create, which is exactly the non-obvious behavior an agent needs.

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 core behavior is front-loaded in the first sentence and the branches follow in logical order, with no filler. It is dense and long, but nearly every clause carries operative semantics; only the error-flag paragraph feels slightly downstream of what a first read needs.

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 non-idempotent, open-world write with no output schema, the description covers matching rules, ignored-parameter semantics, and error-state flags (custom_food_created, write_committed), which is unusually complete. It stops short of describing the full return payload or how the automatic meal determination from meal_time resolves, leaving minor residual ambiguity.

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?

Schema description coverage is 0% across 11 parameters, so the description must carry the load and it does: every arg is annotated, including formats (YYYY-MM-DD, HH:MM:SS in account timezone), defaults (G, 100, 1), and the crucial 'new food only' scoping that tells the agent which values are silently ignored on a find-hit. It also flags that only serving_qty applies to an existing match.

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 opening line states a specific compound verb and resource: find-or-create a custom food and log it in one step. The body immediately disambiguates the two branches (search hit vs. miss), so an agent knows exactly what the tool does without opening the schema.

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 value proposition (avoids duplicate entries, removes separate search → create → log round-trips) and explicitly routes nutrition/serving edits on an existing food to update_custom_food. It does not explicitly contrast against log_custom_food or create_custom_food, so the when-not guidance is strong but not exhaustive.

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

Deploy Server

Other Tools