mfp_create_custom_food

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

The description adds substantial context beyond annotations: it discloses the cookie-authenticated web endpoint (no browser needed), the nuanced net-carbs behavior tied to country_code, the fact that MFP has no update endpoint, and that it returns the food id. This is exactly the kind of behavioral detail that helps an agent avoid errors. No contradiction with 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every paragraph adds critical information: purpose, nutrition coverage, carb semantics, and update limitation. It is structured with clear paragraphs and an Args/Returns section. Slightly verbose, but each sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the nutrition model and the critical country_code behavior, the description covers all essential context: what it creates, how it authenticates, what it returns, and how it relates to other tools. The output schema is present, so return-value details are not needed, and the description still clarifies the return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema has rich per-parameter descriptions, the tool description adds concrete behavioral detail not in the schema: the verified example of how carbs/fiber store under different country_code values, and the warning 'Never pre-add fiber.' This goes beyond merely listing parameter names, earning an above-baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence clearly states the action ('Create a private custom food') with a specific resource ('MyFitnessPal account'). It distinguishes from sibling tools like mfp_search_food (searching existing foods) and mfp_delete_custom_food (deleting). The mention of 'private' and 'custom' further differentiates it from diary-logging tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains a key usage pattern: the returned id is accepted by mfp_add_food_to_diary, and because MFP has no update endpoint, corrections require creating a new food and deleting the old one. It does not explicitly state when to avoid using this tool (e.g., if a food already exists), but the context is reasonably clear.

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