Skip to main content
Glama
xunji-private-mcp

xunji-private-mcp

by Vdk1639

upsert_custom_food

Destructive

Save or update a custom food with user-confirmed nutrition data and a real source when official search lacks a suitable match; include a unique key for updates.

Instructions

Save a custom food after user confirmation. Use a custom food when official search has no suitable match or the user requests one. For updates, supply its existing uniquekey.

Provide a real nutrition source and known kcal, protein, fat and carbohydrate per 100 g. The source is shown to the user. Omit portion units for gram-based tracking. Use food from the result when recording that food.

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": {
      "name": "<name>",
      "ntr": "<ntr>",
      "nutrition_source": "<nutrition_source>"
    },
    "name": "upsert_custom_food"
  }
}

Input Schema

NameRequiredDescriptionDefault
ntrYes
nameYes
unitsNo
uniquekeyNo
nutrition_sourceYes
client_request_idNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.7/5.0
Behavior3/5

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the write/overwrite risk is known structurally; the description's added value is the user-confirmation prerequisite and the update-via-uniquekey path. However, for a destructive tool it never says that an update overwrites the existing custom food's stored nutrition, nor what the response contains. That leaves a meaningful behavioral gap on a mutation whose annotations flag destructiveness.

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?

Short, front-loaded and mostly waste-free: the first sentence establishes the action and precondition, the next the routing rule, then the payload requirements. Minor issues are the run-together "unique"+"key" token and the terse, slightly ambiguous closing line about using food from the result, which costs clarity without adding much.

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 6-parameter, nested-object, destructive write with no output schema, the description covers inputs and preconditions reasonably well. It does not state what comes back (an agent likely needs the generated uniquekey to update or record the food later) and says nothing about client_request_id, leaving two real gaps against 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?

Schema description coverage is 0%, so the description must carry the load, and it does for most of it: ntr is explained as kcal/protein/fat/carb per 100 g, nutrition_source is explained as user-visible, units explains the gram-based omission rule, and uniquekey explains the update path. It leaves client_request_id entirely undefined and does not explain the nested foodUnit/foodpic members, which is why it is not a 5.

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?

States a specific verb and resource ("Save a custom food") and adds a scope qualifier ("after user confirmation"). It also signals the existence-handling behavior ("For updates, supply its existing uniquekey"), which makes the upsert semantics concrete rather than tautological. Sibling differentiation is present but partial: it contrasts with official search, and only obliquely gestures at the record-writing sibling with "Use food from the result when recording that food."

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?

Gives an explicit when-to-use rule ("when official search has no suitable match or the user requests one") and a concrete update path (supply the existing uniquekey). It also adds a conditional usage note ("Omit portion units for gram-based tracking"). It stops short of five because the boundary against upsert_food_records is only hinted at, not named.

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