Skip to main content
Glama
Alidade MCP

Alidade MCP

Official
by alidade-ai

Update a saved search

update_saved_search
Destructive

Modify a workspace saved search's name, filters, groups, or visibility while leaving omitted fields unchanged; only team-editable searches can be updated.

Instructions

Update a workspace saved search. Only searches with team_edit visibility can be modified — Alidade-curated and view-only searches cannot, and when connected via OAuth only the search's owner can change its visibility. Omitted fields are left unchanged. groups replaces all comparison groups: include each existing group's id (from get_saved_search) to preserve it, since readouts and bulletins pin group IDs and dropping a referenced group is refused. Providing any top-level keyword parameter replaces the whole keyword filter (empty arrays clear it) and switches to one shared filter. With per-group keywords (topicSearchMode perGroup), keyword parameters on a group replace that group's filter; existing groups (by id) without them keep their current keywords, new groups start with none, and when switching to perGroup they start from the shared filter. Searches with dynamic (rule-based) groups accept only name and description changes.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>"
    },
    "name": "update_saved_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesSaved search ID.
nameNoNew name.
groupsNoReplaces all comparison groups. Include an existing group's `id` to preserve its identity; groups without an `id` get a new one.
keywordsNoKeywords to filter post content by. Cannot be combined with `booleanQuery`.
dateRangeNoReplaces the date range. null = all time.
platformsNoReplaces the platform filter. Empty = all platforms.
visibilityNoNew workspace visibility. Setting `team_view` makes the search view-only for workspace members and no longer editable via the API.
descriptionNoNew description; null clears it.
booleanQueryNoBoolean keyword query matching the app's advanced search mode. Syntax: AND/OR/NOT (upper case), parentheses, quoted phrases with optional proximity ("health care"~3 = up to 3 words between, any phrase length, max 20), NEAR/N (either order) and THEN/N (ordered) between terms or groups, wildcards (elect*, wom?n), fuzzy (medicaid~1, max 2). Always use explicit operators between terms. Mixing AND or NOT with OR at the same depth is an error — parenthesize to make precedence explicit ((a AND b) OR c, (a OR b) NOT c). NEAR/THEN bind tighter than AND/OR — parenthesize a proximity expression that sits next to AND/OR ((a NEAR/5 b) OR c, (a OR b) NEAR/5 c). NOT is not allowed inside NEAR/THEN; exclude outside the proximity expression. Matching is exact-token, case- and accent-insensitive (no stemming) — cover word variants with OR or a wildcard (tariff OR tariffs, tariff*). Korean attaches particles to words, so put a trailing wildcard on each Korean term (검색*). Hindi is written in Devanagari and romanized, so OR both forms ((दोस्त OR dost)); Devanagari and Tamil matching ignores vowel signs, so expect some unrelated matches. Comments are ignored by search: // to the end of the line, <<< >>> inline or across lines. Full syntax: https://docs.alidade-ai.com/search-syntax. Cannot be combined with the keyword parameters.
keywordMatchNoWhether posts must match any (default) or all of `keywords`.
excludeKeywordsNoKeywords that matching posts must not contain (exact word/phrase match). Cannot be combined with `booleanQuery`.
topicSearchModeNo`shared`: the top-level keyword parameters apply to every group. `perGroup`: each group's own keyword parameters apply to that group only, and the top-level ones must be omitted. Defaults to `perGroup` when any group has keyword parameters, `shared` when top-level keyword parameters are given, and otherwise (on update) the search's current mode. Switching an update from `perGroup` to `shared` requires the top-level keyword parameters (empty arrays for no filter).
keywordMatchTypeNoExact (default) matches the literal word or phrase; stemmed also matches English word variants (win/wins/winning).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.1.2
    • addedInput schema / properties / groups / items / properties / booleanQuery
      Added value: +{
      +  "description": "Boolean keyword query matching the app's advanced search mode. Syntax: AND/OR/NOT (upper case), parentheses, quoted phrases with optional proximity (\"health care\"~3 = up to 3 words between, any phrase length, max 20), NEAR/N (either order) and THEN/N (ordered) between terms or groups, wildcards (elect*, wom?n), fuzzy (medicaid~1, max 2). Always use explicit operators between terms. Mixing AND or NOT with OR at the same depth is an error — parenthesize to make precedence explicit ((a AND b) OR c, (a OR b) NOT c). NEAR/THEN bind tighter than AND/OR — parenthesize a proximity expression that sits next to AND/OR ((a NEAR/5 b) OR c, (a OR b) NEAR/5 c). NOT is not allowed inside NEAR/THEN; exclude outside the proximity expression. Matching is exact-token, case- and accent-insensitive (no stemming) — cover word variants with OR or a wildcard (tariff OR tariffs, tariff*). Korean attaches particles to words, so put a trailing wildcard on each Korean term (검색*). Hindi is written in Devanagari and romanized, so OR both forms ((दोस्त OR dost)); Devanagari and Tamil matching ignores vowel signs, so expect some unrelated matches. Comments are ignored by search: // to the end of the line, <<< >>> inline or across lines. Full syntax: https://docs.alidade-ai.com/search-syntax. Cannot be combined with the keyword parameters.",
      +  "maxLength": 5000,
      +  "type": "string"
      +}
    • addedInput schema / properties / groups / items / properties / excludeKeywords
      Added value: +{
      +  "description": "Keywords that matching posts must not contain (exact word/phrase match). Cannot be combined with `booleanQuery`.",
      +  "items": {
      +    "maxLength": 200,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 100,
      +  "type": "array"
      +}
    • addedInput schema / properties / groups / items / properties / keywordMatch
      Added value: +{
      +  "description": "Whether posts must match any (default) or all of `keywords`.",
      +  "enum": [
      +    "any",
      +    "all"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / groups / items / properties / keywordMatchType
      Added value: +{
      +  "description": "Exact (default) matches the literal word or phrase; stemmed also matches English word variants (win/wins/winning).",
      +  "enum": [
      +    "stemmed",
      +    "exact"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / groups / items / properties / keywords
      Added value: +{
      +  "description": "Keywords to filter post content by. Cannot be combined with `booleanQuery`.",
      +  "items": {
      +    "maxLength": 200,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 100,
      +  "type": "array"
      +}
    • addedInput schema / properties / topicSearchMode
      Added value: +{
      +  "description": "`shared`: the top-level keyword parameters apply to every group. `perGroup`: each group's own keyword parameters apply to that group only, and the top-level ones must be omitted. Defaults to `perGroup` when any group has keyword parameters, `shared` when top-level keyword parameters are given, and otherwise (on update) the search's current mode. Switching an update from `perGroup` to `shared` requires the top-level keyword parameters (empty arrays for no filter).",
      +  "enum": [
      +    "shared",
      +    "perGroup"
      +  ],
      +  "type": "string"
      +}
  2. First observedv0.1.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds real operational detail: omitted fields are preserved (PATCH semantics), groups wholly replaces the group list, dropping a group pinned by readouts or bulletins is refused, and setting team_view makes the search no longer editable via the API. These are consequences an agent could not infer from the schema or annotations alone.

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 purpose and eligibility rules, then replacement semantics, then the dynamic-group exception — a sensible order for a destructive multi-parameter tool. It is long and the perGroup sentence is a dense run-on ('existing groups (by id) without them keep their current keywords, new groups start with none, and when switching to perGroup they start from the shared filter'), which could be tightened without losing content.

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?

For a destructive 13-parameter mutation with no output schema, the description covers preconditions, replacement rules, pinning refusals and mode interactions thoroughly. The one gap is that it never says what the call returns (the updated search object or just an acknowledgement), which matters more given there is no output schema.

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

Parameters5/5

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

Schema coverage is already 100%, so the baseline would be 3, but the description supplies interaction semantics the schema does not encode: top-level keyword parameters replace the entire filter and collapse to shared mode, per-group keywords replace only that group's filter, preserved groups without keywords keep their current filters while new groups start empty, and switching to perGroup seeds from the shared filter. That meaningfully disambiguates how the 13 parameters interact.

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?

Opens with a specific verb and resource: 'Update a workspace saved search.' It immediately scopes the operation to workspace searches and, in the same sentence, bounds eligibility (only team_edit visibility), which cleanly separates it from create_saved_search, get_saved_search and delete_saved_search.

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?

States explicit when-not conditions: Alidade-curated and view-only searches cannot be modified, OAuth connections restrict visibility changes to the owner, and searches with dynamic rule-based groups accept only name and description. It also names the prerequisite tool ('include each existing group's id (from get_saved_search)'), giving the agent a concrete retrieval step before calling.

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