Well

Describe entity

well_describe_entity

Read-only

Get a grounded description of ONE entity — what it is, using its real field values and one hop of its related records, never a guess. Reach for this on a SPECIFIC question about one already-identified entity that wants a short inline answer: "does this person pay on time", "anything unusual about this invoice", "summarize this company's payment history". An open-ended "tell me about X" / "show me all you got on X" / "everything you have on X" / "what do you have on X" ask is NOT this tool: call well_show_record_graph_summary for it, even for a single entity, because that card carries the entity's graph plus its written summary.

Resolve X to its record id first (well_query_records or well_get_entity), then call this tool with that root + id — never a guessed id or a name string.

Returns description (what this is), positive (an unusually good fact, when one stood out), and flag (an unusual or concerning fact, when one stood out) — positive and flag are "" when nothing stood out, which is expected and not an error. Set deep_search=true only when the ask needs the workspace's recorded notes/context on this entity too, not for a plain describe.

When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.

Input Schema

Name	Required	Description
`id`	Yes	The entity's public UUID (the value of its *_id field, e.g. company_id).
`root`	Yes	Which records root the id resolves on, e.g. companies \| people \| invoices.
`deep_search`	No	Also search the workspace's recorded notes/context for this entity (additive, not a wider relationship crawl). Default false.
`workspace_id`	No	Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which.
`conversation_id`	No	The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation.
`workspace_scope`	No	Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace.

Output Schema

Name	Required	Description
`flag`	Yes	An unusual or concerning fact, when one stood out. "" when none did.
`error`	No
`success`	Yes
`positive`	Yes	An unusually positive fact, when one stood out. "" when none did.
`description`	Yes	What this entity is, grounded in its real fields and one-hop neighborhood.
`fallback_line`	Yes	A plain, non-LLM line to fall back on when description is "".
`conversation_id`	No	The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.
`newly_connected`	No	Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later.
`resolved_workspace`	No	The workspace that answered, when the caller named none and the token authorizes several.
`conversation_id_note`	No	Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.
`conversation_id_source`	No	Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 28, 2026
- removedOutput schema / properties / resolved_workspace / properties / name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / resolved_workspace / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed1 schema field changedOct 12, 2026

changedOutput schema / properties / newly_connected / description

Previous value: -"Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. Start the reply with one line per entry, in the person's language: \"<name> is connected.\". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later."New value: +"Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: \"<name> is connected.\". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later."

Changed1 schema field changedOct 8, 2026

addedInput schema / properties / workspace_scope

Added value: +{
+  "description": "Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace.",
+  "enum": [
+    "family"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 6, 2026

addedOutput schema / properties / newly_connected

Added value: +{
+  "description": "Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. Start the reply with one line per entry, in the person's language: \"<name> is connected.\". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "name": {
+        "type": "string"
+      },
+      "service_id": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "name",
+      "service_id"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

AddedOct 1, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, so the description is free to add the non-obvious behavior: the one-hop grounding limit, the 'never a guess' constraint on ids, the fact that positive/flag may legitimately be empty strings rather than an error, and workspace resolution behavior when the token spans multiple workspaces. These are traits an agent could not infer from the annotations or schema.

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?

Front-loaded with the core definition, then routing rules, then return shape, then workspace/permission notes — a sensible order. It runs five paragraphs for a two-required-parameter read tool, and the workspace_id paragraph is a near-echo of the schema, so it is slightly longer than strictly necessary.

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?

Output schema exists, yet the description still adds value by explaining the empty-string semantics of positive/flag that the agent must not treat as failure. Combined with routing rules, id-resolution prerequisite, deep_search condition, and multi-workspace handling, nothing needed to call it correctly is missing.

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 baseline is 3; the description still adds meaning by insisting root+id be resolved from a real record rather than a name string or guessed id, which is a semantic constraint the schema (which only says 'public UUID' and lists the root enum) does not convey. The deep_search and workspace_id guidance largely restates the schema descriptions, keeping this below a 5.

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?

States a specific verb and resource ('Get a grounded description of ONE entity') and immediately bounds the scope: real field values plus one hop of related records, never a guess. It names the sibling it is not (well_show_record_graph_summary) with the exact phrasing that distinguishes the two, so an agent can route without opening either 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?

Gives concrete positive triggers in user-question form ('does this person pay on time', 'anything unusual about this invoice'), then explicitly excludes open-ended 'tell me about X' asks and names the alternative to call instead — even for a single entity. It also states the prerequisite step (resolve X via well_query_records or well_get_entity first) and when to set deep_search.

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

All Well tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?