ESQ Matching Engine

Save or change search filters (older name)

update_matching_preferences

DestructiveIdempotent

Older name of update_listing_criteria, kept until 2026-12-15; use update_listing_criteria. Save or change search filters (location, budget, timing, practice area, language, sort priorities) for this conversation. No personal contact details. Deleted automatically after 24 hours. This is a listing service, not a lawyer referral service. No lawyer pays for placement or ranking of any kind.

Input Schema

Name	Required	Description
`criteria`	Yes	Fields to set or change. Do not include names, emails or phone numbers.
`clear_fields`	No
`preference_set_id`	No	Omit to create a new set

Output Schema

Name	Required	Description	Default
`note`	Yes
`criteria`	Yes
`retention`	Yes
`expires_at`	Yes
`preference_set_id`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 6, 2026

changedInput schema / properties / criteria / properties / description / description

Previous value: -"Short description of the legal need in the user's words. Used only to pick a practice area; not stored."New value: +"Short description of the legal need in the user's words. Used only to pick a practice area and to notice a cost concern (then free and low-cost options are shown); not stored."

Changed1 schema field changedNov 5, 2026

changedInput schema / properties / criteria / properties / priorities / description

Previous value: -"What matters most, in order. Shifts ranking weights."New value: +"Older way to pick an order; used only when sort is not given (price: published_fees_first, speed: availability_reported_first, experience: years_licensed, proximity: nearest_office)."

Changed9 schema fields changedOct 25, 2026

changedOutput schema / properties / criteria / anyOf

Previous value: -[
-  {
-    "additionalProperties": {},
-    "properties": {
-      "county": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "practice_area": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "state": {
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {
+      "county": {
+        "x-observed-types": [
+          "string",
+          "null"
+        ]
+      },
+      "practice_area": {
+        "x-observed-types": [
+          "string",
+          "null"
+        ]
+      },
+      "state": {
+        "x-observed-types": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / expires_at / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
addedOutput schema / properties / expires_at / x-observed-types
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / note / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
addedOutput schema / properties / note / x-observed-types
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / preference_set_id / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
addedOutput schema / properties / preference_set_id / x-observed-types
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / retention / type
```
Removed value: -[
-  "string",
-  "null"
-]
```
addedOutput schema / properties / retention / x-observed-types
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed1 schema field changedOct 24, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "criteria": {
+      "anyOf": [
+        {
+          "additionalProperties": {},
+          "properties": {
+            "county": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "practice_area": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "state": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "expires_at": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "note": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "preference_set_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "retention": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "preference_set_id",
+    "criteria",
+    "expires_at",
+    "retention",
+    "note"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedOct 22, 2026

changedInput schema / properties / criteria / properties / client_side / description

Previous value: -"Which side the user is on. ESQ CoPilot has no record of which side lawyers usually represent, so results carry a warning to ask."New value: +"Which side the user is on. ESQ Matching Engine has no record of which side lawyers usually represent, so results carry a warning to ask."

changedInput schema / properties / criteria / properties / deadline_date / description

Previous value: -"A deadline the USER reported (hearing, filing, response). ESQ CoPilot does not verify or calculate deadlines."New value: +"A deadline the USER reported (hearing, filing, response). ESQ Matching Engine does not verify or calculate deadlines."

Changed2 schema fields changedOct 20, 2026

changedInput schema / properties / criteria / properties / client_side / description

Previous value: -"Which side the user is on. ALCBar has no record of which side lawyers usually represent, so results carry a warning to ask."New value: +"Which side the user is on. ESQ CoPilot has no record of which side lawyers usually represent, so results carry a warning to ask."

changedInput schema / properties / criteria / properties / deadline_date / description

Previous value: -"A deadline the USER reported (hearing, filing, response). ALCBar does not verify or calculate deadlines."New value: +"A deadline the USER reported (hearing, filing, response). ESQ CoPilot does not verify or calculate deadlines."

First observedOct 17, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, and the description adds genuinely new behavioral facts: no personal contact details are kept, the record is auto-deleted after 24 hours, and it is a listing rather than referral service with no paid placement. It does not explain what 'destructive' means in practice (that clear_fields can remove stored criteria), which is the one behavior an agent most needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

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

The deprecation notice is correctly front-loaded, but the description then bundles marketing/legal disclaimers ('not a lawyer referral service', 'No lawyer pays for placement or ranking of any kind') that do not help an agent decide or invoke. Roughly half the text is boilerplate rather than behavioral or parameter guidance.

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

Completeness4/5

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

An output schema exists, so return values need no explanation, and retention, privacy scope and the deprecation path are all covered. What remains missing is the clear_fields mechanism for a tool flagged destructiveHint=true — an agent could call it without knowing which fields it can remove or what happens to unspecified criteria.

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

Parameters3/5

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

Schema coverage is 67% on a large nested object, and the description only sketches the areas covered by 'criteria' (location, budget, timing, practice area, language, sort priorities) without distinguishing criteria from clear_fields or explaining preference_set_id's omit-to-create semantics. That is a marginal addition over the schema, appropriate for a mid-coverage nested schema.

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?

The description states a specific verb+resource ('Save or change search filters ... for this conversation') and immediately identifies the tool as the older alias of update_listing_criteria, so an agent knows both what it does and how it relates to the sibling without opening any schema.

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?

It gives an explicit routing directive ('use update_listing_criteria') plus a sunset date (2026-12-15), which is strong when-to-use guidance. It stops short of saying whether this alias should ever be preferred (e.g., legacy clients) and does not point at the read counterpart get_search_filters for inspecting existing filters.

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

All ESQ Matching Engine 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?