Skip to main content
Glama
Alidade MCP

Alidade MCP

Official
by alidade-ai

Create a saved search

create_saved_search

Create a workspace saved search with curated entity comparison groups and filters for team analysis, reusable by other tools via savedSearchId.

Instructions

Create a workspace saved search with manually curated comparison groups of entities (get entity IDs from find_entities). It appears in the app for all workspace members and can be used as savedSearchId in the other tools. Keyword filters accept either keywords/excludeKeywords or a booleanQuery — not both. To give each group its own keyword filter, set the keyword parameters on the groups instead (topicSearchMode perGroup). Dynamic (rule-based) groups can only be created in the app.

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": {
      "name": "<name>",
      "groups": "<groups>"
    },
    "name": "create_saved_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesSaved search name.
groupsYesComparison groups (max 8). Analytics responses are keyed by group.
keywordsNoKeywords to filter post content by. Cannot be combined with `booleanQuery`.
dateRangeNoDate range filter. Omit or null = all time.
platformsNoPlatforms to include. Omit or empty = all platforms.
visibilityNoWorkspace visibility: `team_edit` (default — any workspace member can edit) or `team_view` (view-only for members; also not editable via the API afterwards).team_edit
descriptionNoOptional description.
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

A3.9/5.0
Behavior4/5

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

Annotations already declare this is a non-idempotent write that is not destructive, so the bar is lower; the description still adds real behavioral context by stating the saved search is visible to all workspace members in the app and becomes a reusable savedSearchId. It does not contradict the annotations and adds the app-only limitation for rule-based groups, though it says nothing about what happens on failure or about the created resource's identity.

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?

Four sentences, each carrying a distinct decision (identity, visibility, filter mutual exclusion, per-group filters) with the purpose front-loaded. No padding, though the parenthetical asides make the middle sentences denser than necessary.

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 12-parameter creation tool with full schema coverage and annotations covering the safety profile, the description supplies the workflow context an agent needs. The one notable gap is that no output schema exists and the description never says what the call returns (presumably the new saved search including its savedSearchId).

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 description coverage is 100%, including long booleanQuery syntax notes and the topicSearchMode fallback rules, so the description's parameter remarks (keywords/excludeKeywords versus booleanQuery, perGroup, entity IDs from find_entities) largely restate what the schema already documents. Per the rubric, a 3 baseline applies when the schema carries the parameter semantics.

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?

The description opens with a specific verb and resource ('Create a workspace saved search') plus the shape of the payload ('manually curated comparison groups of entities'), and it names find_entities as the source of entity IDs. It does not explicitly contrast itself with update_saved_search or delete_saved_search, so the sibling distinction is only implied.

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 concrete routing guidance: fetch entity IDs via find_entities, use the result's ID as savedSearchId in other tools, and fall back to the app for dynamic rule-based groups. It also explains the keyword-vs-booleanQuery choice and the perGroup mode. What is missing is an explicit statement of when to call update_saved_search instead of creating a new one.

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