# Assist With Animals: for AI assistants

Assist With Animals keeps a person's durable records of the animals in their life: their own, animals they know, wild ones they recognise, and the encounters they have. The AI reasons and researches; the site stores and shows; the person decides.

MCP endpoint (streamable HTTP, OAuth): https://www.assistwithanimals.com/mcp
Protected resource metadata: https://www.assistwithanimals.com/.well-known/oauth-protected-resource/mcp
Sign-in: the person signs in with their own Assist With Animals account (OAuth with dynamic client registration). No API keys.
Protocol: MCP 2026-07-28 (stateless); 2025-06-18 and 2025-03-26 initialize are also answered.
People manage connections at https://www.assistwithanimals.com/settings/ai.

## Rules
- You may record, propose and draft. You never confirm an identification, a link, a diagnosis or a decision on your own.
- Use observation kind `noticed` only for the person's own first-hand words.
- Corrections are additive; originals stay readable.
- Respect location precision; never reveal more than a record allows.
- Writes take an `opKey`; retrying the same call with the same key never saves twice, and reusing a key for different content is refused (opkey_conflict).
- Batches (tools with an `items` array: animals_add_observations, animals_save_kinds, the items of animals_save_list) are not all or nothing. Each item is checked and saved on its own, and the result lists every item as {index, ok: true, id} or {index, ok: false, code, reason} (reason starts "Animals refused:"), with saved and refused counts. When at least one item saved, an opKey retry replays that same per-item result; send the refused items again, fixed, under a new opKey. When every item is refused, nothing is saved, the call is refused (code nothing_saved, the same per-item result under structuredContent.batch) and the key stays free.
- No tool archives, restores or deletes; those stay with the person on the website.
- If the person disconnects your connection or turns writing off, calls answer with code GRANT_REQUIRED and the link https://www.assistwithanimals.com/settings/ai; pass it on rather than signing in again.
- animals_connection_status is never blocked: it says what this connection may do. A removed connection lists only that tool, and calling it explains the removal and links to https://www.assistwithanimals.com/settings/ai to reconnect.
- Every refusal starts with "Animals refused:" and says what to do next.

## Tools (31)

### Start here
- animals_connection_status (read): Says what this connection may do right now (read, and whether writing is on), the name it appears under, and the link where the person manages it: https://www.assistwithanimals.com/settings/ai. It is never blocked. If the person removed this connection, it is the only tool listed and calling it explains that and how they reconnect.
- animals_get_workspace_brief (read): Start here. Returns what is in this person's Animals workspace (counts of animals, groups, species, encounters, places), the Queue waiting for you, care routines due soon, their Preferences for how you should work (units, tone, what to check) and recent activity. Preferences are guidance, never permission.

### The Queue and suggestions
- animals_list_queue_work (read): The questions and jobs the person left for you. By default returns waiting and working items, oldest first, with the records each one is about and the depth they asked for (quick, careful, deep). Work one with animals_get_context_brief, then animals_save_complete_result.
- animals_save_complete_result (write): Finish one Queue item in one call: your answer (a short summary plus optional full body), any research write-up to keep in the Library, any observations to add to the records, and the records you saved. If you need the person before you can answer, pass `question` instead and the item waits on them. Your answer is shown with your name on it.
- animals_add_queue_item (write): Write down a question or job the person asked to put off ("look into that later"), so it is waiting in their Queue. Only for work the person asked for; your own ideas go to animals_suggest.
- animals_suggest (write): File your own idea for the person to accept or dismiss: a question worth asking, a routine worth adding, a duplicate you noticed, feedback about this site. Nothing happens until they click.
- animals_propose_tendency (write): Propose a preference you noticed ("they weigh in grams", "they want sources cited"). It waits for the person; only they write their Preferences.

### Reading records
- animals_find (read): Find records by words when the person names something loosely ("the grey hen", "Bramble", "the pond"). Optionally limit to record types. Returns ids, labels and a short excerpt. Then read one with animals_get_context_brief.
- animals_get_context_brief (read): Everything about one record in one bounded read: its fields, recent timeline (observations and measurements with who wrote each), identity claims and candidate identifications, group members and counts, links to other records, research on the shelf about it, routines, open Queue items, documents and files, and the Preferences that apply to it. Page older timeline with `cursor`.

### Recording
- animals_add_observations (write): Add dated observations and measurements to animals, groups, places or encounters, all in one call. Use `noticed` only for the person's own first-hand words; your own reading is `ai_interprets`. To fix an earlier entry use animals_correct_observation, which keeps the original. Each item is checked and saved on its own: the result lists every item as {index, ok: true, id} or {index, ok: false, code, reason} with saved and refused counts, so one bad item does not stop the others. If at least one item saved, an opKey retry replays this same result; send only the refused items again, fixed, under a new opKey.
- animals_correct_observation (write): Saves a corrected entry that supersedes an earlier one. The original stays readable. You may correct entries an AI wrote. The person's own entries are theirs to correct on the site; if they tell you one is wrong, add a new observation with what they said.
- animals_save_animal (write): Create an individual animal (omit animalId) or update one. An individual is one animal tracked over time; a flock or herd is a group (animals_save_group). Relationship says how the person knows it: encountered (seen, not followed), following (a wild or neighbouring animal they keep track of), in_care (theirs, fostered or in rehab), past (died, released or rehomed). Species and breed are proposed with animals_propose_identification.
- animals_save_group (write): Create or update a group (a household, flock, herd, colony, litter, the frogs in a pond). Add dated counts per kind (an estimate unless you counted exactly; earlier counts stay as history) and members, either existing animals or named members without their own record.
- animals_save_encounter (write): Record a sighting or moment ("a heron at the pond at dusk") with the person's words kept exactly as given, or update one. An animalId proposes a same-individual link for the person to confirm; it never sets or replaces the encounter's settled animal. Link a group or place when known. Location precision protects sensitive species and private places: exact, generalised (shown only roughly), delayed (shown later) or omitted. Use generalised when unsure.
- animals_propose_identification (write): Propose what an animal or an encounter is. For an encounter, files a candidate identification with confidence and evidence for and against. For an animal, files an identity claim (species, breed, sex, age, markings). Your proposals stay unconfirmed until the person accepts them on the site.
- animals_save_kinds (write): Find or create species and breed records (group → species → breed). Returns ids, reusing an existing record of the same name. A kind is shared by many animals; never fold an individual into its species. Each item is checked and saved on its own: the result lists every item as {index, ok: true, id} or {index, ok: false, code, reason} with saved and refused counts, so one bad item does not stop the others. If at least one item saved, an opKey retry replays this same result; send only the refused items again, fixed, under a new opKey.
- animals_link_records (write): Propose a typed link between two records (same_individual, parent_of, offspring_of, bonded_with, lives_at, seen_at, preys_on, related_to) with confidence and evidence. Links you propose wait for the person. Set onPersonsRequest only when the person explicitly told you the link is true; it is then saved as their confirmation, made through you.
- animals_save_place (write): Create or update a place: a property, an area within it (a paddock, the pond), a spot (a nest box, a feeder) or a wild place (a nature reserve). Places nest via parentId. Precision says how exactly the place may be shown; private homes and sensitive sites default to generalised.
- animals_save_person (write): Create or update a person the animals deal with: a vet, trainer, farrier, rescue, sitter, co-carer or breeder. Observations can then name them as the provider.
- animals_save_topic (write): Create or update a topic (a behaviour, a condition, a care practice, a habitat, a piece of equipment) that research, documents and lists can be about. Reuses a topic of the same name.
- animals_save_routine (write): Create or update a care routine (worming every 90 days, hoof trim every 6 weeks) for an animal, group or place, or log that it was done. Exceptions name animals the routine does not apply to. Never invent dosages; record what the person or their vet stated.

### Research, documents and lists
- animals_library_catalogue (read): The person's Library: research write-ups, sources (books, papers, sites, vet leaflets) and standing instructions. Filter by shelf, by the record an item is about, or by words. Check here before researching something again; then read full text with animals_library_checkout.
- animals_library_checkout (read): Full text of up to 10 Library items with their citations and version history.
- animals_build_packet_draft (read): Gathers one animal's or group's records for a date range into a draft packet (for a vet visit, a sitter, a rehabber): observations, measurements, routines, providers and open questions, banded by who wrote them. Nothing is saved. Review it with the person, then save the final text with animals_save_document.
- animals_save_library_item (write): Keep research, a source or a standing instruction in the person's Library, with your name on it. Research is your write-up with citations; a source is a book, paper, page or leaflet; an instruction is something the person wants followed. Updating keeps earlier versions.
- animals_save_document (write): Save a new version of a document: a vet packet, a handover for a sitter, a care sheet, a profile, a remembrance. Earlier versions stay. Say what it drew on. A packet, or any document drawing on health observations, must keep three headings so the person's words and yours stay apart: "## What you recorded", "## Your AI's interpretations" and "## Documents and references" (animals_build_packet_draft gives you this shape). Interpretations are labelled as yours, never as a diagnosis.
- animals_save_list (write): Create or update a list (a checklist, species to watch for, questions for the vet) and add items, which may point at records. The life list builds itself from encounters and needs no saving. The list itself saves whole; each new item is added on its own and comes back as {index, ok, id} or {index, ok: false, code, reason}, so a refused item does not stop the list or the other items.

### Photos and files
- animals_get_evidence_batch (read): Returns up to 8 of the person's photos or files as images you can see (a resized copy) plus their captions and what they are attached to. Use it for identification and for checking what a photo shows; say plainly when you have not seen a file.
- animals_begin_upload (write): For a photo or file you can send as bytes over HTTP. Returns a one-time upload URL (good for an hour, up to 20 MB); PUT the exact bytes there, then call animals_finish_upload with the token. Small files (up to 2 MB) can go inline with animals_attach_inline_file instead.
- animals_finish_upload (write): Confirms an upload started with animals_begin_upload, checks the bytes and attaches the file. Returns the file id.
- animals_attach_inline_file (write): Attach a small photo or file sent as base64 (up to 2 MB) to a record, with a caption.