Skip to main content
Glama
alidade-ai

Alidade MCP

Official
by alidade-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Update a saved search

update_saved_search
Destructive

Modify a team-editable workspace saved search by updating its name, filters, groups, or visibility while preserving existing group IDs and leaving omitted fields unchanged.

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 keyword parameter replaces the whole keyword filter (empty arrays clear it). Searches with dynamic (rule-based) groups accept only name and description changes.

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`.
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. First observedv0.1.1

TDQS

A4.2/5.0
Behavior5/5

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

Goes well beyond the destructiveHint/idempotentHint annotations: it states omitted fields are untouched, that groups replaces the entire collection and dropping a pinned group is refused, that any keyword parameter replaces the whole keyword filter, and that empty arrays clear filters. That is exactly the mutation semantics an agent needs before calling a destructive tool.

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-loads the core purpose and eligibility, then moves to replacement semantics. Every sentence carries information, though the keyword/booleanQuery and groups clauses are dense enough that an agent must parse carefully; nothing is wasted but it is close to the size limit for easy scanning.

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?

With 12 parameters, no output schema, and a destructive mutation, the description covers eligibility, replacement semantics, and the main failure mode (pinned group IDs). It omits what a successful response returns and how validation failures surface, but the annotated safety profile plus the parameter rules leave little ambiguity about how to call it.

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 would be 3, but the description adds cross-field behavior the schema only states per-property: the groups replace-and-preserve-by-id rule, whole-keyword-filter replacement, and the dynamic-group restriction on which parameters are honored. It does not add anything about id or visibility formatting beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Update a workspace saved search') and immediately bounds the scope with visibility restrictions. It references get_saved_search as the source of group IDs, so the agent can infer its relation to siblings, but it never explicitly contrasts with create_saved_search or 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 Guidelines4/5

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

Strong when-not guidance: only team_edit searches are editable, Alidade-curated and view-only searches are excluded, OAuth connections restrict visibility changes to the owner, and dynamic-group searches accept only name/description. These are real gating conditions an agent could otherwise get wrong. It stops short of routing to an alternative tool when the update is refused.

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