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

Annotations already declare write/non-idempotent/non-destructive. The description adds real context beyond them: the search becomes visible to all workspace members and can be referenced as savedSearchId by other tools, plus the constraint that dynamic groups are app-only. It omits duplicate-name behavior and the irreversibility of team_view (which the schema carries, not the description).

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

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

Four short sentences with the resource and scope front-loaded, followed by constraints. Minimal waste, though the mutual-exclusion sentence duplicates schema text and could be trimmed.

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

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

For an 11-parameter creation tool with no output schema, the description covers the highest-value unknowns: cross-tool reuse, workspace visibility, ID sourcing, and the app-only dynamic-group limitation. Remaining gaps (name collisions, failure modes) are modest.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented in detail, including the booleanQuery syntax and the mutual exclusions. The description only restates the 'not both' rule, so baseline 3 applies; no new syntax or format guidance is added.

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

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

States a specific verb+resource ('Create a workspace saved search') and immediately qualifies what the groups contain ('manually curated comparison groups of entities'). It distinguishes itself from siblings by pointing at find_entities for ID sourcing and by scope (workspace-wide, reusable as savedSearchId), though it never explicitly contrasts with update_saved_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives actionable preconditions: get entity IDs from find_entities, keyword filters accept one of two modes, and dynamic/rule-based groups must be built in the app instead. It does not state when to choose this over update_saved_search or what to do if a similarly named search already exists.

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

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

Goes well beyond the destructiveHint/idempotentHint annotations: it discloses that deletion is permanent, the OAuth-vs-API-key ownership asymmetry, and that the operation is refused while other resources reference the search. This is exactly the behavioral context an agent needs before a destructive call.

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

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

Three tight sentences: action and scope first, then failure conditions, then the sibling alternative — no filler, front-loaded with the verb.

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

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

For a single-parameter destructive tool with annotations and no output schema, the description covers permissions, blocking dependencies, and the alternative path; nothing an agent needs to invoke it correctly is missing.

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

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

The single 'id' parameter is fully documented in the schema (100% coverage, UUID format), so the description adds no syntax detail. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource ('Permanently delete a workspace saved search') and immediately narrows the scope to team_edit visibility, distinguishing it from siblings like update_saved_search and get_saved_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly names update_saved_search as the alternative when the goal is modification rather than removal, and states the precondition (dependent readouts/bulletins/chat projects must be cleared first), which tells the agent when the call will fail.

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

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

Annotations already cover read-only safety, so the extra burden is low. The description still adds a real behavioral trait beyond annotations: the tool cannot be called without a filter, preventing a wasted call that would otherwise look legal from the schema. It does not describe result ordering or what happens when filters are combined, leaving a minor gap.

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

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

Three sentences, zero filler, and the mandatory-filter constraint is front-loaded immediately after the purpose statement so the agent cannot miss it. The downstream-usage note is a single tight clause that earns its place by enabling a follow-up call.

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

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

For a 7-parameter, zero-required, read-only lookup with no output schema, the description covers the decisive facts an agent needs: what it returns, the filter requirement, and how to reuse IDs. It omits any hint about result shape (entity list plus nextCursor) or paging behavior, though the cursor parameter's own schema description carries that.

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

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

Schema description coverage is 100%, so the baseline is 3. The description beats that by stating a cross-parameter constraint (the anyOf requirement) that the JSON schema does not encode at all, which is genuine meaning beyond the individual field descriptions. It does not clarify how search, category, and savedSearchId interact when combined.

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

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

States a specific verb (find) and resource (tracked entities), and enumerates concrete entity types (brand accounts, executives, campaigns) so the agent knows what domain object comes back. It implicitly distinguishes itself from the singular get_entity sibling by describing a filtered collection search rather than an ID lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly states the precondition 'at least one of search, organizationId, or savedSearchId is required — there is no unfiltered listing', which is critical given the schema declares zero required parameters. It also tells the agent what to do with the results, feeding entity IDs into get_analytics and search_mentions, giving concrete downstream routing.

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

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

With readOnlyHint=true already covering safety, the description adds non-obvious behavior: content-analysis metrics are computed over the analyzed-post subset, so their denominators are smaller than raw post counts. It also clarifies override semantics (date/keyword/platform params replace saved-search settings). It stops short of describing response shape or cost/latency characteristics.

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

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

Front-loaded with purpose, then scoping rule, then metric list. The metric enumeration is long but each item is meaningfully distinct and helps metric selection. Minor density cost from listing all eleven families inline rather than grouping.

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

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

For a 15-parameter analytics tool with no output schema, the description covers scoping, metric choice, per-group breakdown, and the analyzed-subset denominator caveat — enough to call it correctly. It could say more about what each result group contains, but the metric list implies the shape.

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

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

Schema coverage is 100%, so every parameter is already documented in structured fields and the baseline is 3. The description reinforces the most consequential semantics — savedSearchId inherits groups/platforms/date/keyword filters, entityIds is a single ad-hoc group — but adds little that the schema descriptions do not already state at greater depth.

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

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

States a specific verb+resource ('Aggregated analytics for a scope of entities, broken down per comparison group') and enumerates the eleven metric families so an agent knows the full output surface. It is clearly distinguishable from siblings like search_mentions (raw posts) or get_saved_search (scope definition) because it is the aggregation endpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly prescribes scoping: 'exactly one of savedSearchId (recommended ...) or entityIds (ad-hoc, treated as a single group); the other parameters filter or override the scope,' and notes 'themes ... requires taxonomy.' It does not name sibling alternatives (e.g. use search_mentions when raw posts are needed instead of aggregates), so a 4 rather than 5.

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

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

readOnlyHint already covers the safety profile, and the description goes beyond it by disclosing the returned field set and explicitly scoping out per-channel account details. No mention of behavior when the ID is unknown (error vs empty), which is the remaining gap for a single-record lookup.

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

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

Three sentences, front-loaded with the operation and return shape, then usage, then the alternative. No filler and nothing repeated from the schema or annotations.

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

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

A one-parameter read tool with annotations present and no output schema — the description compensates by enumerating the returned fields and carving out the get_analytics boundary. Nothing needed to invoke it correctly is missing.

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

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

The single parameter is fully documented in the schema (uuid format and pattern), so the baseline is 3. The description adds real value by telling the agent where a valid entity ID can be sourced from, which the schema cannot express.

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

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

Specific verb+resource ('Get one tracked entity by ID') followed by an enumeration of exactly what comes back: name, category, description, organization, and the four website slots. An agent can immediately tell this is a single-record fetch, distinct from the list-oriented find_entities sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Gives concrete entry points for the ID — search_mentions results, saved-search groups, channel-presence analytics — and explicitly routes per-channel account data to get_analytics with the channel-presence metric. It stops short of saying what to do when you only have a name and no ID (i.e., use find_entities first), which is the one obvious routing decision left unaddressed.

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

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

readOnlyHint=true already covers the safety profile, so the description's real contribution is disclosing the return shape (groups, counts, platforms, filters) in the absence of an output schema. It doesn't cover behavior on a nonexistent or deleted id, which is the remaining gap.

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

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

Two sentences, zero filler, and the return-content enumeration comes before the alternative-tool pointer, so an agent learns what it gets first and where to go next second.

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

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

For a one-parameter read tool with no output schema, enumerating the returned fields and pointing to find_entities for drill-down covers nearly everything an agent needs. Only error/not-found behavior is unaddressed.

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

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

Single id parameter with 100% schema description coverage and a uuid format/pattern constraint, so the schema already does the work. The description never mentions the id argument or its expected form, though there was little left to add.

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

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

States a specific verb ('Get') and resource ('one saved search's configuration') and then enumerates exactly what configuration fields come back: comparison groups, entity counts, platforms, date range, keyword filters. That level of specificity distinguishes it cleanly from list_saved_searches and get_entity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The second sentence gives a concrete routing rule with the exact parameters to pass: use find_entities with savedSearchId and groupId to enumerate member entities. It doesn't address when to prefer list_saved_searches or update_saved_search, but for the main ambiguity (config vs. members) guidance is explicit.

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

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

readOnlyHint=true already declares the safety profile, so the description's job is to add context — which it does by disclosing the diagnostic purpose and the exact informational payload returned. It stops short of stating there are no side effects or whether the call is rate-limited itself, but the added context is meaningful.

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

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

Two sentences, zero waste, and the payload description is front-loaded before the usage hint. Every clause carries information an agent would otherwise have to discover by calling the tool.

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

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

There is no output schema, so the description must describe return values — and it does, listing five distinct fields. Combined with the annotations and the zero-parameter schema, an agent has everything needed to call it correctly and interpret the result.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the empty object schema is self-evident. Baseline 4 applies since nothing is left ambiguous about invocation inputs.

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

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

States a specific verb and resource (identify the calling workspace) and enumerates exactly what is returned: name, API access tier, auth method, rate limit, and monthly post-quota status. No sibling tool overlaps this self-introspection role, so an agent can select it unambiguously.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly names a usage context: 'Useful as a first call to verify the connection works and see what access is available.' That covers the when, but gives no exclusions or alternatives for the case where the agent already knows its workspace context.

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

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

readOnlyHint=true already declares this is a non-mutating read, so the description's burden is lighter. It adds useful domain context (workspace-scoped visibility, breadth of tracked organization types) but says nothing about pagination behavior, result ordering, or what happens when the filter matches nothing.

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

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

Two short sentences, no repetition, with the scoping constraint front-loaded and the relational context second. Every sentence earns its place.

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

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

For a read-only list tool with full schema coverage and a readOnly annotation, the description supplies what the structure does not: what a 'tracked organization' is and how it relates to entities. A minor gap is the absence of any hint about pagination defaults or result shape, though pageSize/cursor docs partly cover this.

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

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

Schema description coverage is 100%, so all four parameters (type, cursor, search, pageSize) are already documented in the schema with an enum and bounds. The description adds no additional meaning about parameter interaction, so baseline 3 applies.

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

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

States a specific verb ('List') and resource ('tracked organizations'), enumerates the entity categories covered, and scopes it to what 'the workspace can access'. It does not name a sibling alternative, but the second sentence clarifies the relationship to find_entities, making the role of this tool easy to place.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The note that 'each entity returned by find_entities belongs to one of these organizations' implies the intended use (resolving an entity's parent organization, or discovering available orgs before filtering). There is no explicit when-to-use/when-not or reference to alternative tools such as get_workspace_info, so guidance is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine context about curation scope (workspace-shared vs Alidade-curated), but says nothing about pagination behavior, result ordering, or what the workspace sees when a saved search is curated vs user-created.

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

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

Three tight sentences: scope first, resource definition second, downstream routing third. Every clause carries information an agent needs, and the recommended-use cue is placed where it will be read.

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

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

For a zero-required-parameter read tool with 100% schema coverage and no output schema, the description supplies the conceptual model (what a saved search bundles) and where to go next. The only real gap is return-shape/pagination behavior, which the schema partially covers via nextCursor.

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

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

Schema description coverage is 100% (cursor, search, pageSize are all documented in-schema), so the baseline is 3. The description does not add any further meaning about how the name filter or paging interacts with the curated/workspace-shared split.

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

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

States a specific verb (list) and resource (saved searches) with explicit scope: workspace-shared plus Alidade-curated. It also defines what a saved search contains (comparison groups, platform filter, date range, keyword filters), which distinguishes it from the sibling get_saved_search (single item) and from create/update/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.

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

Explicitly says to pass the returned id as savedSearchId to get_analytics or search_mentions, and declares itself "the recommended starting point for analytics questions." That names the alternatives and the condition that selects them, leaving little to inference.

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

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

Beyond the readOnly annotation, the description discloses quota consumption per returned post, API-tier requirements, default page size, pagination caution, and a platform-specific caveat that X posts omit text and engagement metrics while retaining identifiers and labels. These are exactly the behavioral details an agent needs before spending quota or interpreting results.

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

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

The description is dense but front-loaded with purpose and scope, then quota, filter semantics, and the X caveat. Every sentence carries operational information; however, the long parenthetical label list and nested caveats make it somewhat packed.

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

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

For a 20-parameter, read-only search tool with no output schema, the description covers the key unknowns: quota cost, API tier, pagination behavior, filter conjunction semantics, default ordering, and platform-specific field omission with X post IDs provided for lookup. Nothing critical for correct invocation is absent.

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

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

Schema coverage is already 100%, so the baseline is 3. The description earns above baseline by explaining how label filters combine: any value within a filter matches, and all filters must match. It also points to get_analytics for analogous scope parameters, but individual parameter formats remain in the schema.

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

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

The description states a specific resource and scope: the individual posts behind analytics numbers, with content-analysis labels. It explicitly links and differentiates from get_analytics by describing mentions as the underlying posts, and the default ordering is stated. The only minor gap is that the sibling semantic_search_mentions is not named, but purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It gives clear operational guidance: requires the mentions API tier, consumes monthly post quota, keep pageSize small, paginate only when needed, and label filters match any value within a filter and all filters across filters. It does not explicitly compare against semantic_search_mentions, so the agent must infer when to use semantic search instead.

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

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

Beyond the readOnlyHint annotation, the description discloses critical operational traits: results are sorted most-relevant-first, returned posts omit content-analysis labels, the mentions API tier is required, every returned post counts against the monthly quota, and X platform posts omit text and metrics but include X post IDs. These details materially affect how an agent should invoke the tool.

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

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

Despite covering many caveats, the description is front-loaded with purpose, then alternatives, scoping, quota, and platform caveats in a logical order. Every sentence carries actionable information with no filler.

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

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

With no output schema, the description explains what results contain (post text, metrics, entity), ordering, and what is omitted for X posts. Combined with annotations, it gives an agent everything needed to call the tool correctly, including quota and API-tier prerequisites.

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

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

Schema coverage is 100%, and the schema already documents limit defaults, query semantics, date overrides, platform values, and savedSearchId keyword behavior. The description reinforces a few of these (keep limit small due quota, fold keywords into query) but adds little parameter-level meaning beyond the schema itself, so baseline 3 applies.

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

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

The description names a specific verb and resource ('Find posts by meaning'), explains the mechanism (pure vector similarity, no keyword matching), and explicitly distinguishes itself from the sibling search_mentions. An agent can tell immediately what this tool does and how it differs from keyword-based alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It explicitly routes the agent: use search_mentions for chronological listings, keyword filters, or labels. It also explains how to scope with savedSearchId or entityIds and warns that saved-search keyword filters do not apply, instructing the agent to fold important terms into query instead. Usage conditions and alternatives are fully covered.

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

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.

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.

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.

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.

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.

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.