Skip to main content
Glama
Sign In
Ferret

Ferret

by ferret-project
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Add an item from a photo

add_item_from_photo

Adds a home-inventory item from a photo, saves it immediately with the image, and uses background vision to suggest its name, brand, model and serial for confirmation.

Instructions

Creates a new item from a photo: it's saved straight away (as "New item" unless you give a name) with the photo attached, and the vision model reads it in the background. About 20 seconds later get_item shows its suggested name, brand, model and serial — confirm with the person, then apply with update_item. Use it when the person sends a picture of something to add; for a photo of something already in the inventory use add_photo. Put it somewhere with locationId or containerItemId.

Input Schema

NameRequiredDescriptionDefault
dataYesThe image (or PDF, for a document) as base64; no data: prefix
nameNoIts name, if the person said it; otherwise it's "New item" until confirmed
filenameNoThe file's name, with its extension ("receipt.pdf")photo.jpg
locationIdNoWhere it's kept, from list_locations
containerItemIdNoOr the box it's in (an item with isContainer)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.1
    • addedInput schema / properties / containerItemId / description
      Added value: +"Or the box it's in (an item with isContainer)"
    • addedInput schema / properties / filename / description
      Added value: +"The file's name, with its extension (\"receipt.pdf\")"
    • addedInput schema / properties / locationId / description
      Added value: +"Where it's kept, from list_locations"
    • addedInput schema / properties / name / description
      Added value: +"Its name, if the person said it; otherwise it's \"New item\" until confirmed"
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare this is a non-destructive write with no external side effects. The description adds the critical behavior an agent cannot infer: the item is saved immediately as "New item", vision runs asynchronously, results appear after ~20 seconds via get_item, and update_item applies the confirmed values.

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?

Three dense sentences that are well front-loaded with the action, then the async lifecycle, then the sibling disambiguation. Slightly packed, and the trailing placement sentence reads as an abrupt addendum, but nothing is wasteful.

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?

With no output schema, the description carries the return path itself: the immediate write, the background vision pass, and the ~20 second get_item/update_item confirmation loop. For a 5-parameter async ingestion tool, that is everything an agent needs.

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 coverage is 100%, so the schema baseline is 3. The description adds a genuine cross-parameter constraint not encoded in the schema — that locationId or containerItemId should be supplied — plus the default naming behavior when name is omitted.

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?

"Creates a new item from a photo" is a specific verb+resource, and the description immediately distinguishes it from add_photo (existing inventory item) and implicitly from create_item (no photo). An agent knows exactly what this 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 Guidelines5/5

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

Explicit trigger ("when the person sends a picture of something to add"), explicit exclusion with a named alternative ("for a photo of something already in the inventory use add_photo"), and a prerequisite ("Put it somewhere with locationId or containerItemId").

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