LiveCRM

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

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, so the bar is lower, yet the description still adds real behavioral context: reads a local mirror, calls no CRM API, "spends nothing, changes nothing," and clarifies the return shape ("`matched` is the whole count; the sample is capped and says so"). It also warns that the read-side freedom to omit `root` must not reach the write scope, which is meaningful operational context.

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?

Purpose and the no-run routing note are front-loaded, which is correct. But the body runs long and partly re-teaches filter-tree construction that the schema's FilterGroup/FilterCondition descriptions already cover, and the all-caps emphasis adds bulk without new information.

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, and the description compensates by naming the returned pair (`matched` plus a capped sample) and its cap behavior. Combined with the prerequisite note (call list_filterable_fields first, list_crm_connections for the connection id), an agent has everything needed to call this correctly.

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 schema carries the field-level burden, but the description adds compositional meaning not in the schema: filters widen as well as narrow, OR-of-synonyms nests inside an AND, and every node carries its own `kind`. Some overlap exists (the schema's `root` description also states that omitting it counts every record), so it is strong rather than exceptional.

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?

Opening sentence states a specific verb and resource ("Count the CRM records matching a filter, and return a small sample") and immediately frames the scope as a local-mirror read rather than a CRM call. It distinguishes itself from the run-composition siblings explicitly ("If you are composing a plan, you do not need this"). An agent can tell this apart from list_runs/preview_records_run 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.

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

Gives an explicit when ("a population question a PERSON asked -- 'how many contacts have no mobile phone'") and an explicit when-not (composing a scope for a run needs no counts and no record ids). It even prescribes the calling pattern: ask a synonym set as one OR-group call, not one call per term, with the reasoning (double-counting, lost union) spelled out.

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 annotations: nothing happens until dispatched, one message per owner (not per record, with a concrete 40-contacts/3-reps example), no CRM writes, and crucially that a sent message cannot be recalled. It also discloses preconditions and failure modes (needs Slack + owner mappings; no Slack connection fails the run; an unmapped owner is reported per record). The irreversibility note is consistent with destructiveHint=false, which refers to data destruction, not message recall.

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?

Core purpose is front-loaded in the first sentence, which is good. But the message-writing guidance balloons into a verbose past/future-tense essay with a 'four composed plans in a row' anecdote and heavy all-caps emphasis — the actionable rule ('say what the reader should do, not what happened') could be stated in a fraction of the space.

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 moderately complex mutation tool with no output schema and 100% schema coverage, the description leaves nothing essential out: it explains dispatch semantics, the no-disposition constraint, the per-owner batching, aliases for the surrounding workflow (list_filterable_fields, list_crm_connections), and the failure modes.

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 is 3, but the description adds real meaning: filter_spec 'DESCRIBES a population' resolved at dispatch, object_type is the scope of whose owners get told, and the message should be written to a person about their records rather than to a record. That is value beyond the field descriptions.

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 ('Create a run') with the exact behavior stated: it tells each record's OWNER something over Slack. It actively distinguishes itself from sibling create_*_run tools by stating it changes no records, writes nothing to the CRM, and creates no tasks. An agent can tell it apart from create_assignment_run/create_mass_update_run without opening their schemas.

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 when-to-use triggers ('let the reps know about their accounts that X', 'alert the owners of these contacts') and a when-not by contrasting it with 'every other one that carries a filter.' It stops short of naming a specific alternative sibling tool by name, so routing is implied rather than 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?

Annotations only give coarse flags (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds the behavior that actually matters: the run carries no payload, configuration is read live at dispatch, OwnerId is unconditionally OVERWRITTEN with no distinction between unowned and already-owned records, and a credential may request review but never release it. The overwrite disclosure slightly outpaces the coarse destructiveHint=false, but it refines rather than reverses the annotation.

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 tool description is three tight sentences with no waste: mechanism first, then the no-payload/config-at-dispatch constraint, then the overwrite warning and the scoping remedy. The safety-critical constraint (OVERWRITES) is capitalized and front-loaded where an agent will see it.

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 5-parameter mutation with no output schema, the definition covers nearly everything needed to invoke it correctly: required calls, scoping semantics, validation timing, and the destructive-write caveat. The one gap is that it never says what creation returns (a run id, a run object, or nothing), which an agent dispatching a follow-up may want.

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, and much of the filter_spec wording duplicates the schema. The description still earns above baseline by explaining parameter absences (no assignment_spec, no mode, no strategy/field/pool, no write_back) and the validation timing (object_type and filter_spec validated at creation so bad input fails there rather than as a dispatch-time decline).

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 concrete verb+resource (create an assignment run) and then unpacks the actual mechanism — read a configured field, map its value to a rep pool, pick a rep by the pool's rotation, write OwnerId. It explicitly distinguishes itself from the nearest sibling ("NO assignment_spec, and that is the whole difference from a Mass Update run"), so an agent can route between create_assignment_run and create_mass_update_run without opening either schema.

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 explicit when-to-scope guidance ("scope with filter_spec if you mean only unowned records"), prerequisite calls (list_filterable_fields for field names/operators, list_crm_connections for a connection_id), and states what is deliberately NOT an input and why (no strategy/field/pool because that is per-tenant configuration read at dispatch; no write_back because the write is unconditional). Alternatives and exclusions are both named.

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 only say readOnlyHint=false/destructiveHint=false; the description adds genuinely valuable behavior the annotations can't convey: it does nothing until dispatched, never merges, and requires specific templates. This directly explains the deferred side-effect model and clarifies that merging is a separate per-group decision.

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 well-ordered sentences: purpose first, then the non-obvious behavioral caveats, then the template requirement. Minimal waste, though the template sentence overlaps with the schema's own description of template_ids.

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?

Given a complex tool with a nested filter tree and 6 parameters, the description covers the critical behavioral model (detection-only, dispatch-gated, per-group merge). It does not describe the return value, but the schema carries all parameter detail, so the remaining gap is minor.

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 schema already documents all six parameters including template_ids (one per kind) and filter_spec. The description restates the template requirement but adds little beyond what the schema says. Baseline 3 applies when the schema does the heavy lifting.

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 run that finds duplicate records') and explicitly scopes what it is NOT ('merges nothing on its own'), routing the merge step to approve_duplicate_group. An agent can distinguish it from the other create_*_run siblings without opening the schema.

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?

Clear context: use it to detect duplicates and queue groups for review, and it names the alternative (approve_duplicate_group) for the merge decision. It also signals the two-step workflow (create, then dispatch). It does not explicitly contrast with other run types, but the detection scope is unambiguous.

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 are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden and does so well: it discloses that dispatching SPENDS money, one credit per record, that credit_cap is required with no default and is the only bound besides scope size, and that templates are human-authored. This is exactly the cost/safety context an agent needs before invoking.

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 the money-spend warning, then the two key parameters, then the workflow hint. Dense but every sentence earns its place; only mildly dense phrasing keeps it from a 5.

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 10-parameter mutation tool with no output schema and minimal annotations, the description covers the critical unknowns (cost, required credit_cap, template authoring, preview step). Remaining parameter detail lives in the 100%-covered schema, so little 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?

Schema description coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it motivates credit_cap as a spend ceiling with no default, explains template_id as a person-authored config governing field mapping and overwrite rules, and warns that nothing but scope size otherwise bounds spend. It is silent on disposition/ask_again_after_days, which the schema already covers.

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 run that fetches missing field values from a provider and writes them to the CRM), and the cost/write nature immediately distinguishes it from sibling create_*_run tools like normalize or segmentation. An agent knows what this does without opening the schema.

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 clear context: list templates with list_rule_templates, read one with get_rule_template, and 'Preview before dispatching' (pointing implicitly at preview_enrichment_run). It does not name that preview sibling explicitly nor contrast with the other create_*_run routes, so the routing guidance is strong but slightly inferential.

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=false, destructiveHint=false, openWorldHint=false, and the description's review-queue framing is consistent with destructiveHint=false rather than contradicting it. It adds genuinely useful undisclosed behavior: the credit economics (one credit per contact first ask, free on re-ask), the de-duplication of recent asks, the workspace per-run cap refusal, and the 'nothing reaches the CRM without a person' review gate. That is real context beyond the annotations, but much of the credit-cap text merely restates the schema's own field description, so it lands at solid-but-not-maximal.

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 the core verb and the enrichment contrast, which is good, but the body is heavily padded with all-caps emphasis and repeats material the schema already carries (credit cap, no object_type, filter_spec scope appear in both places). The shouty formatting and duplicated arguments make it slower to scan than its information content warrants.

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 create tool with no output schema, it covers the full lifecycle an agent needs: dispatch requirement, credit spend mechanics, review-queue disposition, scheduling safety, and scope configuration. Combined with the 100%-covered input schema, nothing material for correct invocation 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?

Schema coverage is 100%, so the baseline is 3; the description earns a 4 by explaining what the schema cannot say — why there is no object_type (always contacts), why there is no disposition ('propose is what this run ALWAYS does'), and the intent behind credit_cap ('if a person asks for a budget, set it here'). It adds rationale rather than field syntax, which is the right layer given the schema already documents each field.

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 job-change run) and pins down exactly what the run asks ('which contacts have changed jobs') and what it queues ('each mover's departure'). It explicitly distinguishes itself from the closest sibling, create_enrichment_run ('AN ENRICHMENT RUN IS NOT THIS... it maps no employer'), and rules out create_records_run/create_alert_run as follow-ups.

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 user phrasings that select it ('check whether our contacts have moved', 'people who are no longer there'), states the precondition ('does nothing until dispatched'), and names the when-not ('no create run or alert run belongs after it'). It also explains the safe-scheduling condition, covering when/when-not/alternative in one pass.

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?

Far exceeds the annotations: it discloses per-platform delete semantics (Salesforce cascade + Recycle Bin with 15-day undo; HubSpot unlink-not-delete + snapshot recreation under a new id), the human-approval requirement ('execute' is refused for deletes), and the side effect that 'propose' still spends enrichment budget. Annotations only say readOnlyHint=false/destructiveHint=false; the description carries all the operational detail.

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 the required-spec rule before the long operational caveats, and the ALL-CAPS signposting aids scanning. It is verbose and the delete paragraph largely duplicates the schema's own delete description, so it is not maximally tight, but given the tool's complexity most sentences earn their 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 9-parameter, high-stakes tool with no output schema, it covers scope, alternatives, approval gates, and cross-platform differences thoroughly. The only gap is that it never states what the call returns (e.g. a run id for later dispatch/approval), which the agent must infer.

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 schema already documents each parameter and its baseline is 3. The description adds genuinely useful meaning beyond the schema — owner_id must be a literal id from list_crm_users, delete must pair with a filter_spec and nothing else, and the propose/queue/execute dispositions — though it also restates much of the delete parameter's own schema text.

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 ('Create a run that sets named fields to declared values across a scoped population, and/or applies Segments') and explicitly distinguishes itself from enrichment ('Every record in scope gets the same change, which is what separates this from enrichment'). An agent can identify the tool's scope and its boundaries with siblings without opening the schema.

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 explicit when-to-use/when-not-to guidance: owner_id is a ONE-TIME correction vs. rule-based ownership via get_assignment_config; delete requires delete=true with filter_spec and nothing else; and it names concrete alternatives (list_crm_users, get_assignment_config, list_filterable_fields). The condition selecting each path is spelled out.

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 only give readOnlyHint=false / destructiveHint=false, which would not tell an agent that this tool writes to the CRM on dispatch. The description supplies that: creation stages a run and the WRITE happens when dispatched, the Default is connection-scoped and person-authored, and editing it has blast radius across unrelated runs. This is exactly the context annotations cannot carry.

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 the core purpose and dispatch behavior, then the rule-selection guidance. Dense but every block carries a decision the agent must make. The heavy all-caps emphasis and the closing aside about what 'a person may genuinely mean' add rhetorical weight that a tighter phrasing could carry.

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?

No output schema exists, and the description does not say what is returned on creation (e.g., a run id for later dispatch/get_run), which an agent orchestrating create-then-dispatch would want. Otherwise it is complete for a write-triggering creation tool: target object, filter semantics, rule selection, and review dispositions are all addressed.

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 still adds meaning by framing template_id as 'the scheme this run applies' and explaining the Default fallback is per-connection and authored by a person, which helps an agent reason about omitting it. It does not add much about disposition or filter_spec beyond what the schema already spells out.

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 + effect: 'Create a run that rewrites field values into canonical form ... and WRITES the result to the CRM when dispatched,' with a concrete enumeration of what normalization covers (phones, country/state, street abbreviations, company suffixes). This distinguishes it clearly from the many sibling run-creation tools (dedup, enrichment, assignment, verification).

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?

Explicit when-to-use guidance: preview rules with preview_normalize_scheme first, use template_id or fall through to the connection Default, and a clear routing rule to create_rule_template for a job-scoped tidy-up. It also names the anti-pattern (editing the Default) with the consequence (changing every other normalize run on the connection).

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 only minimal annotations, the description discloses many behavioral traits: no CRM writes or starts until confirmation, refusal timing for unsupported tools, condition-skipping behavior, no and/or support, and the common count_crm_records guard pattern. This is unusually rich behavioral context.

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 front-loaded with the core purpose and no-op clarification, then proceeds logically through usage, step shape, and conditions. It is long and uses emphatic all-caps phrasing, but almost every sentence carries useful instruction for this complex 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?

Covers the tool's purpose, usage conditions, and step/condition semantics thoroughly. However, with no output schema, it does not state what create_plan returns, and staged-plan behavior is only documented in the input schema rather than the main description.

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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it defines each step as {tool, arguments, title} plus optional when, explains that step refers to an earlier index, lists all operators, clarifies skip-not-failure semantics, and gives a concrete condition example.

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: writing down a sequence of tool calls as a reusable plan. It explicitly distinguishes plans from runs and from one-off dispatch, and clearly says the plan does nothing until confirmed.

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?

Provides explicit usage context: use for repeatable or conditional work, and create a run and dispatch directly for one-off work. However, the claim that 'there is no tool that confirms one' leaves the execution path unclear and appears to conflict with the sibling tool fire_plan.

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 cover the write/safety profile (readOnlyHint=false, destructiveHint=false), and the description adds substantial context beyond them: it SPENDS MONEY (one provider credit per created contact), credit_cap must be >= record_cap, searching is free, tam_check spends credit even on rejects, and account creation avoids duplicating existing accounts.

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 purpose, cost, and the list_search_criteria prerequisite before the template caveats, and each block earns its place for a 12-param money-spending tool. It is dense with capitalized emphasis and some overlap with the schema's own long description, but not padded.

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 complex tool with no output schema, the description covers cost model, refusal behavior at submission vs dispatch, required template mapping, and ordering of preparatory calls — everything needed to call it correctly. Nothing material 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?

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond it: template_id must map LastName (lastname on HubSpot) or the run is refused, a lead config must also map Company, credit_cap relates to record_cap, and fixed-vocabulary criteria are validated here while free-text ones are not.

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 run that searches a provider and creates contacts in the CRM) and explicitly distinguishes itself from every sibling: 'THIS IS THE ONLY TOOL THAT ADDS RECORDS. Every other tool changes records that already exist.' An agent can route to it 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.

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

Gives explicit ordering and prerequisite guidance ('CALL list_search_criteria FIRST', 'list them with list_rule_templates'), states when values are refused here vs discovered at dispatch, and explains why it takes no filter unlike other runs. Alternatives and when-nots are both present.

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 annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing that this WRITES NOTHING TO THE CRM, that the score lands in LiveCRM where it becomes immediately filterable via `<slug>_score`/`<slug>_band`, and that publishing is a separate, optional decision. It even explains the failure mode (run declines rather than fails when no model exists), which is valuable behavioral context.

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 the core action, then structured under caps headers (WHICH MODEL, TO PUT A SCORE IN A CRM FIELD) that make scanning easy. It runs long and has some overlap with the schema's own descriptions, but each section carries distinct routing or behavioral information.

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 mutation tool with no output schema and full schema coverage, the description supplies everything an agent needs: what the run does, what it doesn't write, where the result is stored and how it becomes usable, how the model is resolved, and the boundary against mass-update. Nothing material 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds real value by framing the `publish` parameter's consequence ('writes to the customer's org and this does not') and explaining the template_id resolution ('the template_id you name, or the connection's model for that object when you name none'). It largely restates some schema detail, keeping it from a 5.

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 run that scores a population against a scoring model') and elaborates what the run actually is: a weighted composite over banded inputs with thresholds naming the result. It distinguishes itself from create_mass_update_run and create_normalize_run, so an agent can tell it apart from siblings without opening schemas.

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?

Explicit routing: use list_rule_templates with tool_type=scoring to find models, and use create_mass_update_run with a score_spec when the goal is to write a score into a CRM field. It also states the fallback behavior (no model -> run declines), which tells the agent when this tool is safe to call versus when it needs another tool.

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 annotations: first-match-wins ordering, unmatched records left ALONE unless a default exists, no compute-only form and no write_back field, and the always-writes contract. It also discloses the destructive edge case (clearing a field a rep may be reading) and the cost/SideEffects nuance. This is rich behavioral context over readOnlyHint=false/destructiveHint=false.

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 purpose is front-loaded, but the prose is long and repetitive, restating the always-writes point across multiple all-caps paragraphs and re-arguing the write_back rationale that the schema description already makes. Some sentences could be cut without losing signal.

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, and for a complex multi-object create the description covers scope, bindings, matching order, and default handling thoroughly. It is slightly short on what the create call returns (the run identity/handle) and its relationship to dispatch_run, but the behavioral picture is otherwise complete.

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 is 3, but the description adds conceptual meaning: it explains why each SegmentApplication must bind every referenced label to a real field on THIS object and name the target_field, and why write_back is deliberately absent. These are semantics beyond the raw schema text, though much overlaps with the already-detailed schema descriptions.

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 and scope: 'Create a run that classifies a population into a Segment's named groups and writes each record's winning label to a CRM field.' It also explicitly differentiates from its closest sibling by contrasting with the scoring run ('IT ALWAYS WRITES, unlike a scoring run'), so an agent can separate it from create_score_run without opening either schema.

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 clear context and prerequisites: call list_rule_templates with tool_type=segment to see the Segments and labels, and filter_spec guidance directs to list_filterable_fields. It establishes when the tool applies (label has nowhere else to live) but stops short of an explicit use-this-vs-siblings routing rule for the other create_*_run tools.

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 only declare the safety profile (readOnly false, destructive false, openWorld false); the description goes far beyond by disclosing the two-stage cost model (free CRM bounce lookup first, then provider checks at one verification per address), the check_cap spend limit with least-recently-checked ordering and continuation across runs, the conditional provider dependency, the default rule thresholds (30 days, invalid+disposable), and the side effect of writing the CRM's bounce date and reason. This is unusually rich behavioral disclosure.

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 core purpose is front-loaded and most sentences carry information, but the definition is dense and sprawling, and the parenthetical internal references ('runbook 2026-10-01', 'app/foundation/verification/templates.py') are meaningless to an agent. A fair amount of the staging/cost material is also restated in the schema description, so the length is not fully earned.

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 complex, multi-stage run-creation tool with no output schema, the description covers the execution model, cost, dispatch dependency, downstream run ordering, configuration defaults, and side effects. Nothing an agent needs to decide whether and how to call it 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: it reframes check_cap as the run's SPEND limit with ordering/continuation semantics, explains that filter_spec is a population descriptor resolved only at dispatch (so no ids or counts are needed), and states the scope is always contacts. That is genuine value beyond the schema text.

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 ('Create a run that finds the CONTACTS in a scope whose email is DEAD') and immediately distinguishes itself from the sibling create_* run tools by naming its population (contacts with dead emails) and its output surface (readable through get_run_records). An agent can tell it apart from create_enrichment_run or create_job_change_run without opening a schema.

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 'It does nothing until dispatched' (pointing at dispatch_run), names the ordering constraint in a staged plan ('put it before the Contact Enrichment run'), and describes the downstream branching to Job Change. This is when-to-use, prerequisite, and alternative-selection guidance all in one.

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 destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it enumerates exactly what is destroyed (scope, config snapshot, counts, funnel), asserts irreversibility ("none of which survive anywhere else"), and discloses an authorization restriction and a side effect on duplicate groups.

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?

Dense but front-loaded: the destructive scope comes first, then exclusions, then the permission constraint. The all-caps emphasis on the ownership rule is slightly heavy-handed, but every sentence carries distinct, 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?

For a two-parameter, no-output-schema destructive tool, the description covers purpose, irreversibility, preconditions, refusals, and side effects. Nothing an agent needs in order to call 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?

Schema description coverage is 100% and both parameters are documented in the schema, so baseline 3 applies. The description restates the ownership constraint on run_id rather than adding new syntax or format detail, and says nothing about connection_id beyond what the schema already provides.

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 ("Discard a run") and immediately scopes what that entails: scope, configuration snapshot, counts and funnel. It also names the sibling it is distinct from (reverse_audit_event) and the behavior it does not perform, so an agent can separate it from other delete/undo tools.

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?

Explicit when-not guidance: it does not undo a dispatched run's CRM writes (use reverse_audit_event), duplicate groups are detached rather than deleted, and only runs you created may be deleted — runs made in the interface are refused. This is precisely the routing and precondition information an agent needs before calling.

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 destructiveHint=true and openWorldHint=true, but the description goes well beyond them: it enumerates per-run-type effects, names irreversible actions (Slack messages that cannot be taken back), discloses credit spend per run type, and specifies the exact reversal path via reverse_audit_event. This is exactly the extra context that turns a destructive write into a predictable one.

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 the action and its risk posture, and the long run-type enumeration is dense and information-bearing rather than padding. It runs slightly long and the mid-sentence catalogue of run types could be compressed, but almost every clause 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?

Despite no output schema, the description explains the return behavior fully (returns as soon as work is launched, not on completion) and routes the agent to get_run for status and the funnel for results. For a high-blast-radius action tool, nothing an agent needs to call 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?

Schema description coverage is 100%, so both run_id and connection_id are already documented by the schema, including the "must already exist" and "call list_crm_connections first" hints. The description adds no parameter-level detail beyond what structured fields provide, so the 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+resource ("Start a created run") and explicitly distinguishes itself from the surrounding lifecycle with "THIS IS THE STEP THAT ACTS." An agent can separate it from the create_*_run siblings (which only create) and get_run (which reads) without opening schemas.

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 explicit when-to-use (after creating a run, it must already exist), what to do afterward (poll get_run until terminal, then read the funnel), and names alternatives for reversal (reverse_audit_event). It also flags the propose/queue disposition case where writes are held for a person rather than executed.

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?

Even with destructiveHint=true already declared, the description adds substantial context beyond annotations: it is the step that actually writes to the CRM, may spend provider credits, staged plans write once at the end, the call returns immediately with a firing_id rather than blocking, and inactive or excluded plans are refused with a named reason.

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 key fact — that this tool acts and spends credits — is front-loaded in capitals before sequencing and follow-up details. The paragraph is dense and each clause carries information, though the mid-sentence uppercase emphasis and some qualification clauses are slightly heavier than necessary.

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 two-parameter mutation tool with no output schema, the description covers the async return shape (firing_id), the follow-up tools needed to observe outcomes, the refusal cases, and the reversal route via preview_plan_reversal. Nothing essential to invoking or reasoning about the call 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?

Schema description coverage is 100% and both parameters are already documented in the schema (plan_id points at list_plans, connection_id points at list_crm_connections). The prose carries no additional syntax or format meaning beyond those field descriptions, so the baseline of 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 opens with a specific verb and resource ('Run a plan now: every step in order') and grounds it in a concrete UI analogue ('as the Plans page's Run button does'), so an agent can immediately separate it from create_plan, dispatch_run, and the various create_*_run siblings.

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 clearly says when to use this tool (to fire an existing plan immediately) and chains the follow-up calls (get_plan for step outcomes, get_run for funnels), plus the reversal path. It never names a competing sibling such as dispatch_run to explain why you would fire a plan here rather than dispatch an individual run, so it falls short of full when/when-not coverage.

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?

Adds substantial behavior beyond the readOnlyHint annotation: unconfigured field values are skipped with a reason rather than assigned arbitrarily, a '*' pool absorbs all remaining values including empty ones, and field is null when nothing is configured so every run declines. These are exactly the semantics an agent cannot infer from annotations or schema.

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 and dense with useful detail; every sentence carries semantics. The heavy capitalization and long compound sentences make it slightly harder to scan than it needs to be, keeping it out of the top band.

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 adequately conveys the shape of the returned configuration (field, pools, selection, membership) plus edge-case semantics, and it clarifies read-only scope, so an agent has everything needed to call and interpret 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 description coverage is 100%, so both parameters are already documented in the schema, including the enum for object_type and the list_crm_connections prerequisite for connection_id. The description adds no parameter-level syntax or format detail, so the 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 (get) and resource (assignment/ownership routing config) and then unpacks exactly what the configuration contains: the deciding field, per-value pools, selection method, and membership. It is clearly distinguishable from set_assignment_config, which it names explicitly as the write counterpart.

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 a clear usage context ('the only way to know what one would do before it does it' since runs carry no payload) and names the alternative writer tool with an access caveat. It does not explicitly contrast against other read siblings like get_default_rule_config, so it stops short of full when/when-not 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the prior values are exactly what a reversal restores (linking conceptually to reverse_audit_event), and it explains the deliberate id-suppression design of list_audit_events. It stops short of describing pagination or output ordering, so not a 5.

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 return semantics in the first sentence, then justifies the sequencing. The '301 ids in a history row help nobody' aside is slightly chatty but earns its place by explaining why the sibling cannot substitute, so waste is minimal.

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 carries the burden of describing the return, and it does so at the right altitude: a set of records, each with per-field prior and written values. Left implicit are pagination/limit interaction and the identity/shape of the returned records, which keeps it from a 5.

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 audit_event_id, connection_id and limit (default 50, max 1000) are already documented in structured data. The description adds nothing about parameter syntax or format, only about the returned payload, so the 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+resource: it returns the records one audit event changed, with each field's prior and written value. It explicitly distinguishes itself from the sibling list_audit_events in the same sentence, so an agent can tell the two apart without opening either schema.

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 the exact usage condition ('the second call, made when you need to know what a write actually did rather than that it happened') and names the alternative (list_audit_events) plus why it is insufficient (returns a count, not ids). Nothing is left 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?

With readOnlyHint/destructiveHint already covering the safety profile, the description goes further: it discloses that it reads a local mirror and calls no CRM API, that it returns every catalogued field including custom fields a preview sample leaves empty, and that a missing record yields a 404 distinguishing 'wrong id' from 'unsynced record'. These are behavioral traits the annotations do not carry.

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 keeps every sentence functional, but it is verbose for a single-record read and uses all-caps emphasis that borders on repetitive. The reference-following and comparator content justify their space; a phrase like 'spends nothing and changes nothing' partially restates the 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?

For a 3-param, all-required read tool with full schema coverage and annotations covering safety, the description rounds out what is needed: return content ('every catalogued field'), the no-API/no-cost behavior, and error semantics. No output schema exists, but the return shape is described well enough.

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 is 3, but the description adds meaning beyond the schema: it clarifies that record_id is an id the caller already holds, and shows how object_type/record_id are chained across calls when following a reference like account_id. Enum values and required fields are left to 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?

States a specific verb (Read) and resource (ONE record's fields) and immediately scopes it as a single-record lookup keyed by a known id. It explicitly contrasts itself with count_crm_records, so an agent can separate the two siblings without opening either schema.

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 explicit when-to-use framing ('what does this contact look like', a question about a named record rather than a population), a named negative alternative ('IT IS NOT count_crm_records'), and a follow-up pattern for chasing references ('a contact's account_id names its account... two calls of this tool'). Nothing material is left 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?

Goes well beyond the readOnly/destructive annotations by clarifying that reading has no side effect on the template ('it does not reset a template, which would be authoring') and by disclosing the 404 failure mode for unsupported kind/tool combinations. That preempts the two most likely agent mistakes.

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 definition in sentence one and each following sentence adds a distinct fact (use case, supported kinds, non-mutating behavior). Slightly dense with parenthetical asides, but no sentence is wasted.

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?

No output schema exists, and the description conveys what the return conceptually is (the untouched seeded configuration) plus the failure mode, which is sufficient for a simple read-only lookup. It does not describe the configuration's shape, which is a minor residual gap.

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 baseline is 3; the description adds value by tying 'tool, object and kind' together and clarifying which combinations are actually served versus returning 404, supplementing the schema's enum notes. It does not restate enum values or formats, which the schema already handles.

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: the seeded configuration a Default template holds before edits, scoped to a tool, object and kind. The phrase 'telling an edited rule apart from an untouched one' implicitly carves out its space versus get_rule_template, so an agent can distinguish it without opening another schema.

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 usage contexts (comparing edited vs untouched rules, explaining what a Default does) and states the operational boundary that only dedup kinds and normalize are served while 'anything else answers 404'. It stops short of naming get_rule_template or list_rule_templates as the explicit alternative for reading live configs.

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 establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: the output describes a hypothetical mutation, and this is "the only place the outcome is visible while it is still reversible by not acting" — clarifying the tool's role as a pre-commit inspection step.

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 the core promise ("Everything a merge of this group would do, before it happens") followed by a comma-separated enumeration and a single justification sentence. Slightly dense, but every clause carries information and nothing is wasted.

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 carries the burden of explaining return values — and it does so thoroughly, listing exactly what the agent will see. Combined with the annotation-covered safety profile and the schema-documented params, nothing needed to call or interpret this tool 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?

Schema coverage is 100% and both required parameters (group_id, connection_id) are documented in the schema, including the prerequisite calls list_duplicate_groups and list_crm_connections. The description adds nothing about parameters, so the baseline of 3 is appropriate.

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-like action (dry-run preview of a merge) on a specific resource (this duplicate group), and enumerates exactly what the result contains: survivor, absorbed records, resolved field values with provenance, archived values, and match rationale. This clearly separates it from approve_duplicate_group and reverse_duplicate_group.

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?

"Read this before approving anything" gives clear contextual usage and ties the tool to the approval workflow, implicitly routing the agent to approve_duplicate_group. It does not name a sibling explicitly or state when not to use it, so it falls just short of the 5 bar.

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 only cover the safety profile (readOnly/openWorld/destructive), but the description adds substantial operational context: it reads the stored snapshot only, triggers no provider call, consumes no credits, and makes no CRM change. It further documents freshness.state values (current/stale/refreshing/failed/never_computed) and computed_at, plus the crucial caveat that missing is null on incomplete reads and that inconclusive companies are counted in neither bucket.

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?

It is long and dense, but front-loads the core definition before the caveats, and nearly every sentence carries non-obvious meaning (snapshot semantics, missing-vs-null, overlap_possible, sibling routing). Slightly heavy for a single tool, but not padded.

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 analytical tool with no output schema, the description explains the return shape in detail (TAM/ICP totals, per-slice coverage_pct, by_segment overlap, subscription progress) and warns about the two easiest misreadings. Nothing an agent needs to interpret results 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?

Schema description coverage is 100%, so level, slice_limit, slice_offset and connection_id are already documented, and the description adds little parameter-level syntax. Its mention of passing a slice key to list_whitespace_companies concerns output consumption rather than input semantics, so the 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 precise verb+resource ('how much of the connection's market is missing from the CRM') and enumerates the exact outputs (coverage_pct, by_segment, missing, inconclusive). It explicitly distinguishes itself from get_tam and count_crm_records, so an agent can select it without opening either schema.

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 trigger phrasings ('how much of my TAM is missing', 'which industries have the most whitespace') and explicit negatives ('NOT get_tam... NOT count_crm_records'). It also routes follow-ups to list_whitespace_companies (via slice key) and get_persona_whitespace, covering both when-to-use and alternatives.

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 establish readOnly/non-destructive/closed-world, but the description adds real semantic context beyond them: the distinction between a rule's default and its neutral value, and concrete examples of what a default does (strips company suffixes, formats phones, abbreviates streets) versus neutral (leaves the value alone). It stops short of noting response size or pagination behavior.

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 the core payload, then the default-vs-neutral clarification, then the use cases. Slightly wordy ('Default and neutral differ and both matter') but every sentence carries meaning; 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 must carry the return-value burden, and it does so by enumerating the catalog's contents. It could go further on ordering or size, but for a two-parameter read tool it is essentially complete.

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 both parameters (object_type, connection_id) are already documented in the schema. The description only indirectly reinforces that object_type scopes which fields are returned; it adds no syntax or format detail beyond the schema, so the 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 resource (the normalization option space) and enumerates exactly what it contains: canonicalisable field types with rules, each rule's options, default and neutral values, plus the fields this connection carries. An agent can distinguish it from siblings like preview_normalize_scheme or get_default_rule_config from the description alone.

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 two concrete when-to-use cases: reading it to understand what a normalize template's config means, and checking whether a scheme names only fields the connection has. It doesn't explicitly name competing siblings (e.g., preview_normalize_scheme), so it falls short of a full when-not/alternative statement.

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/non-destructive/openWorld, and the description adds real semantic context beyond them: 'state is attention or no_issues_observed, never healthy' and 'not_observed lists what this cannot see' frame the output honestly, and 'reported, not judged' clarifies that a missing change-stream event is not an error. 'Reads only; changes nothing' merely restates annotations, earning no credit here.

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 body is a single ~150-word run-on sentence that presents an entire output inventory as a comma-and-parenthetical dump rather than front-loading or structuring it. Because no output schema exists the return detail is justified, but the format is poorly scannable and the key purpose statement competes with the enumeration.

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 carries the return-value burden and does so thoroughly, covering state values, not_observed, budgets, review queue, and freshness vocabulary. What's missing is guidance on response size or when to fall back to granular sibling tools, but for an aggregate read tool this is largely complete.

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 both parameters (connection_id, days) are already documented, including the days default and range. The description alludes to 'runs that failed or stalled over the last days' but adds no format or semantic detail beyond the schema, so the 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 opening clause ('Whether this connection's work is going well, in one read') is somewhat soft, but the enumeration of concrete signals (oauth_status, mirror freshness, run failures, review queue, budgets) makes the aggregate read purpose unmistakable. It also distinguishes itself from get_usage_summary by noting budgets are included 'as get_usage_summary reports it.'

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?

Usage is implied ('in one read,' 'Reads only') but there is no explicit when-to-use-this-vs-a-granular-sibling guidance, e.g. whether to call get_operational_health instead of list_runs, get_readiness_scan, or get_usage_summary. The agent must infer that this is the aggregate overview tool.

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/destructiveHint annotations it discloses non-obvious behavior: it reads the stored snapshot only (no provider call, no credits, no CRM change), only accounts carrying a provider company id are counted, at most 500 per refresh (past_cap), unmatched_accounts reports exclusions, and defined is false when the ICP names no people. The definitional rule that 'missing' requires provider people present but no CRM contacts is exactly the kind of semantics an agent cannot infer.

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 purpose and the company-level alternative are front-loaded, but the middle is a dense run-on that jams return fields, definitional caveats, capping behavior and subscription state into one block, compounded by ALL-CAPS emphasis. Almost every clause earns its place, but the wall-of-text formatting makes it harder to scan than it needs to be.

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 carries the full return-shape burden and does so: it names each returned field group (per-persona provider/CRM counts, coverage_counts, average_covered, complete_pct, unmatched_accounts, past_cap, subscription progress). For a filtered analytical read tool, nothing an agent needs to call 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?

Schema coverage is 100%, so the schema already documents limit/offset/coverage/min_missing. The description still adds real meaning: it defines what 'coverage' means per account (not a contact count), clarifies when a persona counts as missing, and points the missing_persona value at the labels/keys listed in target_personas, which the schema only gestures at.

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 opening states a specific verb and resource ('Which of the ICP's accounts are missing target buyer personas') and then enumerates the exact output shape (target personas, per-account coverage, missing personas, average_covered, coverage_counts, complete_pct). It explicitly routes the adjacent company-level case to get_market_whitespace, so an agent can separate it from get_market_whitespace and list_whitespace_companies 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.

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

It gives concrete trigger queries ('which ICP accounts are missing a Sales Leader', 'accounts missing two or more personas', 'how many target accounts have the whole buying committee', where to add contacts first) and names the alternative tool for company-level whitespace. The when-to-use and the sibling-selection rule are both 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description then adds real value beyond that: it explains that absent step outcomes mean the step never ran, that status is a single state with a reason, and what the firing and schedule-state fields convey. It falls short of 5 only because it says nothing about failure modes (unknown plan_id, missing connection) or return size.

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 content is front-loaded onto the primary return payload and every clause carries information – with no output schema, the enum lists (status values, schedule_state values) earn their place rather than being padding. The weakness is structural: it is one long run-on sentence with no breaks, which makes it harder to scan than it needs to be.

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 and a stateful resource (running, needs_input, blocked, failed, stopped, cancelled, ready), the description does the heavy lifting of explaining the return shape and how to interpret partial completion, which is exactly what an agent needs. It is close to complete; only error/boundary 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?

Schema description coverage is 100%, with both plan_id and connection_id documented in the schema, including the 'Call list_crm_connections first' sequencing hint. The description adds no additional parameter meaning. Baseline 3 is appropriate when the schema does the work.

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 very specifically what the tool returns for a single plan: the request, each step's tool and arguments, estimated and actual touches, plus firing and schedule state. The verb is implicit ('A plan in full') rather than an explicit 'returns/reads', and it never names the sibling it replaces (list_plans, get_run), so the agent must infer the single-plan-vs-list distinction. Still, the content is specific enough to separate it from its siblings.

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?

There is no explicit when-to-use or when-not-to-use statement, and no sibling is named as an alternative. What it does offer is interpretive guidance on reading results ('A step carrying no outcome DID NOT RUN... how a plan that stopped part-way is read'), which is genuinely useful at invocation time. That is implied rather than stated usage guidance, so a 3 fits.

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 readOnlyHint annotation: it describes the exact return shape (each plan as ready/needs/not_yet with reasons, id, and scheduled status), discloses that needs/not_yet name what's blocking, and clarifies 'reading it calls no provider and changes nothing' — richer context than the annotations alone provide.

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 the core answer (which plan runs next) and the ordered plan list. The mid-sentence parentheticals make it slightly dense but every clause carries information about states or scope.

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-param read tool with no output schema, the description fully covers the returned states, the ordering, blocking reasons, and the mutation/side-effect boundary. Nothing needed to call 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?

Only one parameter (connection_id) and schema coverage is 100%, with the schema even stating 'Call list_crm_connections first.' The description adds no parameter meaning, so baseline 3 is appropriate.

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 ('which plan to run next') scoped to a connection's latest readiness scan, and enumerates the exact plans returned (Clean-up, Always On, Subscription, Out-of-TAM). Clearly distinguishable from siblings like get_readiness_scan or get_plan.

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?

Explains it reads from the latest readiness scan and explicitly notes scheduling happens elsewhere (Plans page or scan page), implicitly routing the agent away from this tool for that action. No explicit when-not or alternative-tool naming beyond that, so slightly short of 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?

Annotations already declare readOnlyHint/openWorldHint=false/destructiveHint=false, and the description reinforces this with 'calls no provider and changes nothing.' It adds genuine context beyond the annotations — null scan on never-scanned connections, the meaning of not_measured, and credit-wasting run ordering — without describing errors or pagination.

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 content is front-loaded and largely earns its place, but it is delivered as one enormous run-on sentence with a stacked enumeration that is hard to parse. Splitting the return-shape list from the read-only caveat would improve structure without losing information.

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 carries the full burden of describing the return value, and it does so thoroughly: statuses, finding fields, remedies with cost, run sequence, previous_id, and the null case. With both parameters documented, an agent has everything needed to call it correctly.

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 both parameters are already documented in the schema. The description repeats the scan_id/previous_id relationship and omits nothing, but adds little syntax or format detail beyond what the schema provides, matching the baseline 3.

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 ('the connection's latest AI readiness scan') and enumerates the artifact's contents precisely, so an agent knows exactly what it retrieves. It does not explicitly distinguish itself from the close sibling get_readiness_recommendations, which is the only missing piece for a 5.

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 clear context: omit scan_id for the latest, pass a previous_id to compare, and 'starting a scan is a person's act' tells the agent not to hunt for a start-scan tool. No explicit alternative routing against sibling read tools, so it stops short of a 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description goes further by explaining what the returned config actually means (enrichment mapping of provider fields to CRM fields, and whether an existing value may be replaced) and why that determines dispatch overwrite behavior. It omits error cases such as an unknown template_id or mismatched connection.

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, front-loaded with what is returned and followed by the reason to call it. The second sentence is long but every clause carries meaning about overwrite semantics; nothing is 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?

No output schema exists, so the description correctly takes on the burden of describing the return value (full template config, rule contents, mapping semantics). For a two-parameter read tool this is nearly complete; only failure modes and identity of the returned fields' naming are left implicit.

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% and both parameters are documented in the schema, including the prerequisite ordering ('Call list_rule_templates first'). The description adds no parameter-level syntax or format detail beyond that, so the 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 and resource (read one rule template) and clarifies scope by contrast: 'the actual rules, not just its name and kind.' This distinguishes it from the list/create/update/delete siblings, though it never names list_rule_templates directly.

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 a clear, actionable when: 'Read this before naming a template in a run, to see what the run would really do.' The condition for use is explicit, but no alternative (e.g. list_rule_templates for browsing) is named to route the agent away when a full config isn't needed.

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 and destructiveHint=false, so safety is covered. The description adds substantive context beyond them: what the response contains and the diagnostic distinction that an empty run and a no-op run look identical without the funnel — real behavioral insight with no output schema present.

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 what the tool returns, then the usage cue, then the justification. Every sentence carries information, though the em-dash gloss of 'FUNNEL' is slightly verbose.

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 does the work of conveying the return shape (status, counts, funnel-by-reason) and its interpretive value. It omits error/edge behavior for bad run_id or connection_id, but is otherwise sufficient to call correctly.

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 both params are documented in-schema (including the 'call list_runs first' prerequisite), so the baseline of 3 applies. The description adds no additional syntax or format meaning 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?

States a specific verb and resource ('One run's detail') and enumerates the payload: status, written/failed counts, and the FUNNEL by reason. This cleanly separates it from get_run_records (per-record detail) and list_runs (collection).

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?

'Read this after dispatching' gives a clear timing cue, and the closing sentence explains why the tool is needed at all. It does not name alternative tools explicitly, though the schema params route the caller through list_runs/list_crm_connections first.

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 cover the safety profile (readOnly, non-destructive, not open-world), yet the description adds substantial behavior not in any structured field: it is spend-free and mutation-free, it is paged newest-scope-first, and crucially that by_outcome/by_reason are computed over EVERY row while total/records/truncated describe the page. This aggregation semantics is nowhere else and directly affects how the agent interprets 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?

Front-loaded with the core purpose and the key distinction from get_run before the paging and chaining details. It is on the long side with heavy all-caps emphasis, but nearly every sentence carries distinct information about scope, chaining, or pagination rather than 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?

There is no output schema, so the description carries the full burden of explaining the return shape: total, records, truncated, and the all-row aggregation of by_outcome/by_reason. Combined with the dispatched-run precondition and the chaining guidance, an agent has everything needed to call and interpret it correctly.

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 schema already documents all five parameters, establishing a baseline of 3. The description adds page-ordering semantics ('Paged, newest scope first') that no schema field mentions, giving a marginal boost above baseline. It does not add format or syntax detail beyond that.

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 with exact scope: 'WHICH records a run decided about, and what it decided -- one row per record' with outcome, reason, CRM id, and provider id. It explicitly differentiates from its closest sibling: 'get_run answers how many; this answers who.' An agent can tell the two apart without opening either schema.

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 an explicit when-to-use condition ('Read it when the count is not the question: which contacts were skipped and why') and names the alternatives (get_run for counts, create_records_run for chaining via person_ids). It also states the precondition ('Reads a run that has already been dispatched'), which rules out use on un-dispatched runs.

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 the safe-read profile (readOnlyHint=true, destructiveHint=false), yet the description adds real context: it defines TAM membership semantics, discloses null behavior for connections without a TAM, and explains the {"kind": "tam"} filter leaf with its member/core flags. 'Reading it changes nothing' reinforces rather than contradicts the annotations.

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 purpose is front-loaded and the prose is dense but coherent; however, the middle sentence about how a run is scoped via the {"kind": "tam"} filter leaf is tangential to invoking this tool and inflates the length. Tightening would help.

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 convey the return shape. It communicates the semantic content (account/contact counts, ICP counts, null case) but never names the response fields, leaving the agent to infer the actual payload structure.

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?

With 100% schema description coverage and a single parameter, the schema already carries connection_id semantics including the list_crm_connections prerequisite. The description adds nothing about the parameter, so the 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 the precise resource (the connection's TAM) and enumerates its components: an account-level filter, a persona-level filter over contacts, and an ICP layer with counts. That is far more specific than a name restatement, but it never explicitly states the retrieval verb and does not differentiate itself from the sibling get_tam_outward.

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?

No sentence says when to call this versus alternatives such as get_tam_outward or set_tam, and no prerequisite beyond the schema's own 'Call list_crm_connections first' is given. The null case ('Null when the connection has no TAM') is a return-value note, not usage guidance.

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, openWorldHint false, and destructiveHint false, but the description adds meaningful semantics: searches may be wider than the TAM but never narrower, Subscription applies the TAM to returned results, non-carried criteria are listed with reasons, and defined is false when no TAM exists. It also explicitly says reading calls no provider and changes nothing, reinforcing the safe-read behavior.

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 front-loads the core purpose, but it is a dense, run-on block with nested clauses and parentheticals that make it hard to parse. Most clauses contribute domain nuance, but the structure is not concise and could be broken into clearer sentences.

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 carries the burden of explaining the return semantics: provider searches, wider-but-never-narrower behavior, non-carried criteria categories, and the defined flag. It is conceptually complete for a complex read-only TAM tool, though the exact return shape remains somewhat abstract.

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%, and the single connection_id parameter is documented in the schema as the CRM connection with a call-first instruction. The description adds no further parameter-level meaning, so the baseline of 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 states a specific resource and perspective: the provider searches that a connection's TAM compiles to outward for Subscription. It is distinguishable from get_tam, but the dense domain jargon and lack of an explicit sibling comparison keep it from a 5.

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?

No explicit guidance is given on when to use this tool versus get_tam, list_search_criteria, or other TAM-related siblings. The line about reading calling no provider is behavioral, not usage guidance, and the schema note to call list_crm_connections first is not in the description.

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 readOnlyHint/destructiveHint/openWorldHint, and much of the description is output semantics rather than behavior. It still adds genuinely useful behavioral caveats beyond the annotations: charged_unmeasured_runs are "never counted as zero," credits are measured across the whole provider account, and budgets with null mean no limit. It omits auth/permission or rate-limit behavior, so not a 5.

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 purpose is front-loaded in the first clause, and every subsequent sentence carries substantive content needed by a tool with no output schema. However, the sentences are long and parenthetical-heavy (embedded metric definitions, budget caveats), which hurts readability and pushes it below a 5.

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 carries the return-value burden and largely meets it, enumerating records_sent, credits_charged, charged_unmeasured_runs, verifications_spent, last reported balance, CRM write allowance, budgets and notes. It stops short of fully specifying units (currency for credits) and the exact shape of budgets, leaving minor interpretive gaps.

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 schema already documents top, since, until, group_by and connection_id; the baseline is 3. The description adds only a small amount (grouping dimension and "largest first" ordering), and never addresses top or the ISO 8601 date formats, which the schema handles.

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 opening clause states a specific verb and resource (what the connection's runs spent over a date range) plus grouping and ordering, so an agent immediately knows this is a usage/cost report. It is not confused with siblings like get_run or list_runs, but it never names a sibling or explicitly distinguishes itself from them, so it stops short of a 5.

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 a concrete when-to-use: "read it before dispatching to know your headroom," which ties the tool to a workflow decision. It also clarifies the read-only posture ("Reads only; calls no provider"). There is no when-not-to-use or named alternative, so it is clear context without exclusions.

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 the safety profile (readOnly, non-destructive, not open-world), and the description adds substantial context beyond that: default page size of 25, offset paging, that it is scoped to one connection, that attempted-but-unresolved writes are included and surfaced via status, and the precise semantics of the reversible flag and how it changes after an undo. This is exactly the behavioral detail an agent needs before calling it.

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?

It is front-loaded with the core definition and each sentence carries distinct information (scope, reversible rule, pagination, status, filters). It is on the verbose side, with 'newest first' repeated and the reversible invariant given several sentences, but little is truly wasted.

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 carries the return-shape burden and does so: it names the fields per entry (tool, action, record count, success, reversal status, actor type) and explains the status field for unresolved writes. Combined with the annotations, an agent has everything needed to call 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?

Schema description coverage is 100%, so the schema already documents all six parameters, and the description largely repeats it (actor, client_id, limit default, offset paging). The one place it adds detail is the `tool` filter, but its enumerated list omits 'scoring' and 'segmentation' that the schema enum contains, an incomplete duplication rather than an enhancement. Baseline 3 fits since the schema carries the load.

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 opening clause gives a specific verb and resource ('the record of every write this deployment has made to the connected CRM, newest first') plus the exact fields returned (which tool, what it did, record count, success, reversal status). It also names the sibling it pairs with (reverse_audit_event) and the id that connects them, so an agent can distinguish it from get_audit_event_records or list_runs without opening a schema.

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 clearly establishes context for use: inspecting write history, deciding whether a reversal will be accepted, and reversing a run newest-first. It explains the 'reversible' invariant in detail so the agent knows this listing is the source of truth for reverse_audit_event. It does not, however, explicitly contrast itself against siblings like get_audit_event_records or get_run_records, so there is no stated when-not-to-use.

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 readOnly/openWorld=false/destructive=false, so the bar is lower, yet the description adds substantial non-obvious behavior: the full oauth_status value set, the fact that expired means a refused token refresh and that jobs are skipped until reconnect (with an instruction not to retry), and the caveat that `selected=false` says nothing about connectivity. That is exactly the operational context an agent cannot get from structured fields.

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 the imperative "Start here" and ordered from purpose to per-field semantics to decision rules. Information-dense with almost no filler, though the oauth_status sentence is long and stacks five states plus a parenthetical caveat, which slightly hurts scanability.

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 carries the full burden of explaining return values — and it does, enumerating oauth_status states and the selected/is_active relationship. For a zero-param discovery tool, nothing an agent needs before calling it 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?

Zero parameters, so the baseline is 4 per the rubric. The description compensates well by defining the semantics of the fields the agent will act on (id, oauth_status, selected, is_active alias), leaving no ambiguity about what the returned values mean.

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 ("List the CRM connections this tenant has") and immediately names what makes it distinct: it returns the id every other tool requires. This is clearly separable from siblings like list_crm_users or get_crm_record, which operate on records rather than connections.

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?

Explicit routing guidance: "Start here: every other tool must name a connection." It then gives the decision procedure — use the sole connection when there is one, and ask the person when there are several and the request doesn't specify. Both the when-to-use and the when-to-stop-and-ask cases are 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description goes beyond them by disclosing default filtering (active users only unless include_inactive), the rationale for that default, and a real caveat that platform/integration accounts may appear as 'people'.

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 and the name-to-id constraint before any caveats. It is dense and slightly long, but each sentence (default filter, deactivation semantics, platform users) carries distinct actionable information rather than padding.

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 two-parameter read tool with no output schema, the description covers what it returns (ids and people), the default filtering behavior, the sequencing dependency on list_crm_connections, and how the output is consumed downstream. Nothing needed to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains why include_inactive matters (deactivated users can still own records) and reinforces connection_id's dependency on list_crm_connections. That is more than the schema's terse flag description provides.

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 the resource precisely ('the people in the connected CRM') and immediately names the distinguishing output ('the id every owner field carries'). It is unmistakable against siblings like list_crm_connections or list_filterable_fields because it frames itself as the name-to-id resolution step.

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 when to use it: 'THIS IS THE ONLY WAY TO TURN A NAME INTO AN ID', and routes to a concrete consumer ('Use the id as the value when setting owner_id through create_mass_update_run'). It also states the read-owner use case and the condition for include_inactive, leaving nothing 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?

Annotations already cover the read-only, non-destructive profile. The description adds valuable context beyond that: the default exclusion of rejected groups, newest-first ordering, and included fields (status, record count, master, match score). Does not mention pagination limits.

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 tightly written sentences, front-loaded with purpose, then return contents, then filtering behavior. No wasted words.

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?

Covers default behavior, filtering, ordering, and returned fields for a 6-param list tool. Minor gap: no mention of pagination/default limit despite limit/offset params, though that's largely in the schema.

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 parameters are already documented. The description adds the semantic that omitting status excludes rejected groups and that run_id scopes to a single run, but doesn't add syntax 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?

States a specific verb (List) and resource (duplicate groups), plus scope (on this connection, newest first). Distinguishes from siblings like get_duplicate_group (singular) and list_runs by describing the triage-queue content distinctly.

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 describes default behavior (no status returns whole queue except rejected) and how status/run_id narrow results. Lacks explicit when-not-to-use guidance and doesn't name sibling alternatives like get_duplicate_group for fetching a single group.

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 read-only annotations, the description discloses that the tool makes no CRM or provider call, spends no credits, and changes nothing—a strong side-effect statement. It also explains the prerequisite run behavior and the meaning of examined 0, which is important for correct interpretation.

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 front-loaded and each section has a purpose, but it is long (~190 words) with heavy all-caps emphasis and some repetition of what annotations already imply. It could be tighter without losing the essential distinctions.

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?

No output schema exists, and the description supplies the key output detail (each mover carries provider_record_id) plus the examined/moved count semantics. It does not describe the full row shape or pagination, but it covers the prerequisites and composition an agent needs to call and interpret the tool.

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 three parameters are already documented. The description adds a critical constraint on run_id: the run must have observed employer_name, which is not 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 comparison action over an enrichment run's fetched employers and names the sibling it is not (run_job_change_sweep). It clearly distinguishes a finding from an action, so an agent can tell what the tool does without opening the schema.

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 use it after a run has fetched employers, requires the template to OBSERVE employer_name, and warns that a run without that returns examined 0. It names run_job_change_sweep as the alternative that enriches and queues, clarifying when not to use this.

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?

Adds substantial behavioral detail beyond the annotations: picklists truncated at 25 values with values_total, field parameter returning full value lists, alias fields omitted, operators centralized in operators_by_type, and per-org schema variability. Annotations only cover read-only safety; the description carries much more.

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?

Dense and front-loaded with the core purpose, then supporting detail about truncation, aliases, and operators. Every sentence carries information, though it is a fairly long paragraph that could be more scannable.

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 discovery tool with no output schema, the description explains what is returned (field types, picklist values, operators_by_type, values_total), how truncation works, and edge cases like aliases. An agent has everything needed to invoke and interpret results.

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 schema already documents all three parameters including their descriptions. The description adds some meaning (field returns every picklist value unfiltered) but nothing the schema lacks. 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+resource ('List the fields of a CRM object that can be filtered') and scopes it to the connection. Clearly distinguished from siblings like list_crm_connections and count_crm_records, which serve different discovery/counting purposes.

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 instructs 'Call this before composing a filter rather than guessing at field names', giving a clear when-to-use condition. It does not name explicit alternatives or exclusions, but the guidance is actionable.

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 readOnly/openWorld=false/destructive=false, so the safety profile is covered. The description adds real behavioral context beyond that: newest-first ordering, the status lifecycle values, the newest-firing fields, and the schedule fields — useful for knowing what comes back. It stops short of pagination/return-size behavior.

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 what the tool is and what it returns, then closes with the alternative. Dense and long-winded in places, but every clause carries information and nothing is redundant padding.

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 correctly takes on the burden of describing returned fields and mostly succeeds, plus annotations cover safety. The only gap is the unresolved ambiguity between the two senses of 'state', and no pagination guidance beyond the schema.

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 limit/offset/state/connection_id are already documented; baseline is 3. The description restates the `state` enum and hints that it filters lifecycle state, but it doesn't fully disambiguate the collision between the `state` param (active/inactive/superseded/archived) and the runtime 'state' it lists (running/needs_input/...), which is the one nuance an agent would want clarified.

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 (lists plans on this connection, newest first) and enumerates what each entry carries. It also distinguishes itself from get_plan and fire_plan, so an agent can route correctly without opening sibling schemas.

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 clear context for when to use it ('which of my plans need attention is one call', 'this is where it is read back') and names fire_plan as the alternative for running one. No explicit when-not or exclusion, but the routing signal is strong.

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 only cover the safety profile (readOnlyHint, destructiveHint=false), and the description goes well beyond them: it discloses the total-vs-page pitfall explicitly ('total is counted across every pending row, actions is the page you asked for'), the one-connection scoping invariant, and the deliberate inability to mutate. This is exactly the behavioral context annotations cannot carry.

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 in the first sentence and every subsequent sentence carries distinct content (provenance, pagination trap, scoping, no-mutation). The all-caps emphasis and the aside about a past shipped mistake are slightly noisy and cost it a point, but there is no dead weight.

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?

No output schema exists, yet the description enumerates what each row contains (the record changed, the field changes, the reviewer reasoning, the originating run or plan), plus connection scoping and paging semantics. Nothing an agent needs to call this list correctly and interpret the result 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning by hammering the semantics of limit/offset versus the returned total ('THE COUNT IS THE CONNECTION'S WHOLE PENDING TOTAL AND NOT THE PAGE'), which prevents a misread of the limit parameter's scope. It also reinforces the connection_id dependency suggested 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?

States a specific verb and resource ('what is waiting for a person to decide' — listing queued changes), and immediately distinguishes itself from queue_action and the run-producing siblings by declaring it is the only place undecided proposed rows exist. An agent can separate this from list_queue_history, list_runs and list_plans 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.

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

Gives a clear governing condition for use ('THIS IS HOW YOU SEE WHAT YOU PROPOSED') and an explicit exclusion ('YOU CANNOT DECIDE THESE' — approving/rejecting/rolling back belong to a person). It also names queue_action as the producer of these rows. It stops short of routing the agent to a specific alternative for decided/historical rows (e.g. list_queue_history), so it is clear context without full alternative mapping.

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 the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds real behavior: result ordering, single-connection scoping, and the durable, server-enforced nature of rejections. It does not describe return format, pagination, or whether limit truncation is signaled, which is why it falls short of a 5.

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 core scoping and sibling-routing information is front-loaded, which is good. However, the all-caps emphatic sentence largely restates the opening sentence, and the 'not merely rude but a no-op' clause restates the auto-suppression point already made, so roughly two of six clauses are redundant.

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 simple two-parameter read tool with no output schema, the description conveys what rows appear, their ordering, their scope, and how the data should change the caller's next action. 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?

Schema description coverage is 100%, with both connection_id and limit documented in the schema, so the baseline is 3. The description reinforces that results are scoped to one connection but adds no syntax, format, or edge-case meaning beyond what the schema already states.

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 resource and scope: actions a person has already decided, enumerated as executed/rejected/rolled back, ordered newest first. It explicitly distinguishes itself from the sibling list_queue_actions by describing their complementary relationship (a queued row not in list_queue_actions is here). An agent can select between the two without opening either schema.

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 an explicit when-to-use rule: read this before proposing to avoid asking twice. It also names the alternative (list_queue_actions) and the condition that separates them, and warns that re-proposing a rejected change is a suppressed no-op, which is actionable guidance rather than vague 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered, and the description reinforces it ('This tool only reads'). Beyond that it discloses the key behavioral trait that config is nulled out in list results and that every connection is seeded a Default of each kind, which the annotations do not convey. Minor gap: no pagination or result-size guidance.

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 return-shape and read-only points are front-loaded, but the middle sentence is a long catalogue enumerating nine-plus template categories (deduplication, normalize, segment, enrichment, scoring, verification, value maps, TAM, whitespace) that largely duplicates the tool_type enum in the schema. That enumeration is padding against structured data that already lists these values.

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?

Covers the essential context for a filtered-list tool: compact vs full config, seeding behavior, downstream usage, and filtering. No output schema exists, and it partially compensates by describing the compact item shape (id, tool_type, object_type, kind, name). Lacks pagination/limit disclosure, which is the main remaining gap.

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 parameters are already documented, and the tool_type enum explicitly enumerates the filterable tool types. The description adds only loose framing ('Narrow with tool_type, object_type, or kind'), including the example kind values matching/master_record/survivorship, but does not go meaningfully beyond the schema. 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+resource (list rule and mapping configurations on a connection) and immediately defines the compact return shape. Distinguishes itself from the sibling get_rule_template by naming it and describing the difference (compact list vs full config).

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?

Explicit when-to-use: use an id from here as template_id on create_enrichment_run or template_ids on create_deduplication_run. It also names the alternative authoring path (create_rule_template) and notes the permission caveat that not every caller has it, which is genuinely actionable routing guidance.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that: newest-first ordering, the 25 default limit, offset-based paging, and the shape of each returned item. No output schema exists, so the return-shape hints are useful, though 'funnel' is left unexplained.

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 core action and ordering before filters and paging. There is minor redundancy between the returned 'who made it' field list and the actor/client_id guidance, but nothing is wasted.

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 six parameters, full schema coverage, and no output schema, the description is adequate: it covers purpose, ordering, filtering and paging. It omits explanation of the required connection_id workflow (left to the schema) and never clarifies what 'funnel' contains, leaving a small gap for an agent interpreting results.

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 goes further by explaining the actor/client_id distinction ('who made them; each run says who made it and whether an agent did'), which the schema alone does not convey, and it restates the limit default and offset paging semantics.

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 ('List this connection's runs, newest first') and defines the domain term ('A run is one execution of an operational tool over a scoped set of records'). It also enumerates the returned fields (status, counts, funnel), which cleanly separates it from get_run (single) and list_plans (different resource).

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 filtering guidance: pass object_type to narrow by target and actor/client_id to narrow by actor, plus paging via offset. It does not explicitly name an alternative or state when-not to use it, so it stops short of full routing guidance.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description reinforces this with 'reads nothing from the CRM, calls no provider, and spends nothing,' which adds a cost guarantee not present in annotations, but it does not disclose return shape, entry count, or caching/staleness behavior. With annotations carrying the main burden, this is adequate reinforcement rather than rich added context.

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 front-loaded with purpose, then when-to-call, then concrete examples of counter-intuitive values. Every sentence contributes, though the phrasing is dense and the parenthetical analogies to list_filterable_fields make it longer than strictly necessary for a one-parameter read-only list.

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, read-only lookup with no output schema, the description fully explains what comes back (criteria, meanings, cardinality, allowed values) and why it matters. Nothing an agent needs in order to call it correctly or to interpret the result 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?

Schema description coverage is 100% and the single object_type parameter has its enum and description ('Which object the create run targets. Contact only.') documented in the schema. The description adds no syntax or format detail beyond what the schema already provides, so the 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 resource (the search criteria create_records_run accepts) and enumerates what each entry carries: meaning, multi-value behavior, and fixed allowed values. It distinguishes itself from siblings by explicitly likening its role to list_filterable_fields while being about create_records_run search criteria, so an agent can place it without opening a schema.

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 an explicit directive ('CALL THIS BEFORE COMPOSING A SEARCH rather than guessing') and states the failure mode that motivates it: the provider rejects unrecognised values at dispatch, after a run has been created and possibly approved. It also points to list_filterable_fields as the analogous tool for filters, so when-to-use and when-not-to-guess are both 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?

Annotations declare readOnly/openWorld/non-destructive, but the description adds substantial extra context: it reads the provider live, spends no credits, changes nothing in the CRM, caches the whole slice for ten minutes (provider_read_at, provider_cache_until), notes the cache is separate from the stored snapshot, and explains complete=false, pagination and 404 behavior.

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 returned fields and then routes to usage, caching and error handling in a logical order. It is dense and the opening field list is long, but the complexity of caching, pagination and completeness semantics justifies most of the length.

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 complex, provider-backed, cached, paginated tool with no output schema, the description covers return fields, pagination counters, completeness caveats, cache lifetime and error recovery. Nothing an agent needs to invoke or interpret it correctly appears to be 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?

Schema coverage is 100%, so the schema documents all four parameters. The description still adds meaning by tying 'key' and 'level' to get_market_whitespace's levels.<level>.slices output, clarifying how to obtain the values rather than just their types.

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 ('the individual companies one whitespace slice is missing from the CRM') and enumerates the exact returned fields. It is clearly distinguishable from siblings like get_market_whitespace and get_persona_whitespace, and even explains its relationship to the former.

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 use it after get_market_whitespace by passing one of its slice keys and the slice's level, and gives a concrete worked case ('my largest missing ICP companies' → use the ICP level's slices). It also supplies the recovery path for a 404 (call get_market_whitespace again).

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, destructiveHint=false and openWorldHint=false, but the description adds substantial context beyond them: no provider is called, nothing is written, nothing is spent, and `projected_credits` is null when the scan was bounded because a prefix cannot project a population. It also states an honest limitation — it cannot predict how many records would CHANGE — which is exactly the kind of boundary disclosure that prevents misinvocation.

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: the core purpose leads, then the output contents, then the spend semantics, then the limitation. Nearly every clause earns its place, though 'writes nothing and spends nothing' partly restates what the readOnly/destructive annotations already convey.

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 must explain return values, and it does so thoroughly: scope counts, accepted-identifier counts, guard/cap survivors, per-reason exclusions, and the nullability semantics of `projected_credits`. It also closes the loop on what the tool cannot answer, leaving no material gap for a read-only preview tool.

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% and both parameters (run_id, connection_id) are documented in the schema, including their prerequisites. The description adds no syntax or format detail for either parameter, so the baseline of 3 is appropriate when structured fields carry the load.

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 verb and resource — preview what a created enrichment run WOULD do — and enumerates the exact outputs (records in scope, identifier match counts, ambiguity-guard and credit-cap survivors, exclusions by reason). This clearly separates it from create_enrichment_run and dispatch_run, which actually perform the work. An agent can identify the tool without opening the schema.

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?

Usage is strongly implied: it runs 'before it costs anything' and 'calls no provider, writes nothing and spends nothing', which tells the agent to call it prior to dispatching a run. Prerequisites (create the run first, call list_crm_connections first) live in the schema rather than the description. No explicit when-not or named alternative is given, so it falls short of a 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds genuinely new behavior: it writes nothing to the CRM or internally, saves nothing, and previewing does not create or change a template. It also discloses the bounded-scan behaviour and the bound_reached signal, which is not derivable from any structured field.

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 the payoff (what the preview reports) before the mechanics, and every sentence carries information. Slight redundancy remains: the 'takes the scheme itself, not a template id' / 'saves nothing' points are restated in the schema and repeated with emphasis, costing a little efficiency.

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 carries the full burden of describing return values and does so concretely: examined/changed/flagged counts, per-field change counts, before/after samples, and bound_reached. All four parameters are addressed, including the required connection_id path via list_crm_connections, leaving nothing an agent needs to call it correctly.

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 adds real meaning on top: it stresses that `config` is the scheme body rather than a template id (enabling unsaved/hypothetical schemes) and that `filter_spec` scopes the previewed population exactly as a scoped run would, which clarifies semantics the schema only gestures at.

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 ('preview a normalize scheme') and immediately enumerates what the preview returns: records examined, changed, flagged, per-field change counts, and before/after samples. It also distinguishes itself from the run-creating sibling by framing the output as 'What a normalize scheme WOULD do', making it separable from create_normalize_run without opening a schema.

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 explicit routing: pass the `config` from get_rule_template to preview a stored scheme, and call get_normalize_catalog for rules/options, and it explains filter_spec scopes 'exactly as a run would'. It stops short of explicitly contrasting against create_normalize_run ('use preview before committing a run'), so the when-not is implied 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 only declare the read-only/non-destructive safety profile; the description goes well beyond that. It discloses traversal order (newest-first, matching the reversal walk) and, critically, what will be reported as unreversible and why — configuration steps with no audit event and alerts that already reached a recipient. This is exactly the behavioral context an agent needs before acting.

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?

Purpose and safety scope are front-loaded, and the all-caps emphasis on the unreversible caveat makes the key constraint scannable. Slightly long and stylistically dramatic, but each sentence carries distinct information (order, unreversible cases, read-only nature).

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 present, the description carries the burden of describing the return content, and it does: a newest-first list of CRM writes plus unreversible items annotated with reasons. Combined with annotations covering safety, nothing material is missing for correct invocation.

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 three parameters are already documented in the schema (including the firing_id note about per-run firings). The description adds no parameter-level detail beyond that, so the 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+resource (preview what reversing a plan would attempt) and immediately bounds the scope with 'what it cannot touch, before anything is undone.' The 'Reads only; it reverses nothing' line implicitly separates it from the actual reversal siblings (reverse_audit_event, reverse_duplicate_group) without ambiguity.

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 phrase 'before anything is undone' implies this is a pre-flight check to run prior to a reversal, which is useful context. However, no alternative tool is ever named and there is no explicit when-not guidance (e.g. when to skip the preview), so the routing signal is only implied.

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 and destructiveHint=false, but the description adds real behavioral context beyond them: the preview consumes no credit, the projection is a CEILING rather than a guarantee, and company matching on website may shift the count. It does not, however, describe pagination, latency, or error behavior. Strong added value over the annotation baseline.

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 and cost framing, then enumerates the reported fields. Mostly earns its length, though the aside 'there is no reason not to look first' is slightly rhetorical filler and the companies_to_create_at_most caveat is dense. Not wasteful enough to drop below 4 given the density of useful detail.

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 must carry the return-value burden and does so thoroughly: match count against the cap, a ten-person sample with name/title/company, existing-account count, companies to be created, email coverage, and projected spend. Combined with the credit and ceiling caveats, an agent has everything needed to interpret and act on 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?

Schema coverage is 100% with only two parameters, both already documented in the schema ('Create it first', 'Call list_crm_connections first'). The description reinforces the run_id/connection_id prerequisites but adds no syntax or format detail beyond what the schema provides, so the baseline 3 is appropriate.

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 ('preview_records_run' → who a created CREATE run would add and its cost) and immediately distinguishes it from its closest sibling by framing it as the pre-flight check for dispatch_run. It is clearly separate from preview_enrichment_run and preview_normalize_scheme by naming the exact artifact (a CREATE run) it previews.

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?

Explicit when-to-use guidance: 'Call this before dispatch_run every time,' justified by the cost asymmetry (searching is free, only creating is charged). It also states an exclusion/limitation ('It cannot tell you which people are already contacts in the CRM'), so the agent knows what this preview cannot answer.

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 indicate a non-read-only, non-destructive, closed-world tool, and the description adds critical behavior: nothing reaches the CRM, the row waits for a human, the caller cannot approve it, it runs only inside a confirmed plan, and unwritable fields are refused immediately. These disclosures go well beyond the annotations and do not contradict them.

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 long but front-loaded: it states the core action first, then plan requirements, alternatives, field naming rules, and scope constraints. The all-caps callouts make it scannable, though the length is close to over-specified for an agent-facing description.

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?

Given the tool's complexity, required plan-only execution, human review workflow, nested field_changes object, and lack of an output schema, the description is complete enough. It covers what the tool does, when it is refused, what it will not do, and what the reviewer will see.

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 schema already documents all five parameters. The description still adds meaningful semantics: field names must be canonical names from list_filterable_fields, they are translated here, and reasoning is reviewer-facing text rather than a restatement of the field name. It is not fully comprehensive for every parameter, but it meaningfully supplements 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 action: propose ONE field change on ONE named record into the review queue for human approve/reject. It also clearly distinguishes the tool from population-based siblings like create_mass_update_run, so an agent can identify when this tool is the right shape.

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 explicit when-to-use and when-not-to-use guidance: direct calls are refused, it must run as a step in a plan created with create_plan, and create_mass_update_run is named as the better alternative for populations. It also states the supported object scope: contacts, accounts, and leads only.

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 declare destructiveHint=true and openWorldHint=true, but the description adds crucial beyond-annotation behavior: it runs as a background task with asynchronous status transitions, and it is refused unless the event is the newest un-reversed one of its run (grouped by caller_request_id). This is exactly the kind of constraint annotations cannot convey.

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 action in the first sentence, then layers constraints. The parenthetical about caller_request_id grouping is slightly dense, but every sentence earns its place and there is 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?

For a destructive, asynchronous mutation with no output schema, the description covers the action, the async nature, the eligibility constraint, the grouping model (caller_request_id), and the lookup path. Nothing an agent needs to call 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?

Schema coverage is 100% and both parameters already have descriptions pointing to the correct lookup tools. The description adds the conceptual meaning of audit_event_id (must be newest un-reversed of its run) but does not add syntax or format details 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?

States a specific verb (undo/reverse) and resource (one recorded CRM write) and the precise effect: restoring every field to its prior value. It clearly distinguishes itself from siblings like reverse_duplicate_group and preview_plan_reversal by scoping to a single audit event.

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 the prerequisite lookup tools (list_audit_events, list_crm_connections per schema) and explains the acceptance rule: only the newest un-reversed event of its run is accepted. It explains why older events are refused, and points to the `reversible` flag as the routing signal.

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 annotations (readOnly=false, destructive=false, openWorld=true) by disclosing cost mechanics (one credit per contact first enriched, free after), that credit_cap is required and caps spend, that a cap above the workspace max is refused, that nothing lands in the CRM without review, and that it returns a task id. These are exactly the behavioral facts an agent needs before invoking a spending mutation.

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?

Purpose is front-loaded in the first clause and every block carries a distinct operational warning (no dispatch, credit spend, cap behavior). It is dense and the heavy all-caps emphasis and repetition around 'review queue' cost it a point, but there is little genuinely wasted text.

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 complex, cost-bearing, non-idempotent batch tool with no output schema, the description supplies everything needed: what it produces (task id, movers surfacing in the queue), the side-effect sequence it triggers, the spend model, and the required cap. Nothing material to correct invocation 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?

Schema coverage is 100% and the schema prose is already rich, so baseline is 3. The description still adds decision-relevant meaning: that credit_cap is where a stated budget goes, that a scope exceeding it leaves contacts unasked rather than unmoved, and that omitting filter_spec sweeps and charges for the entire book. It slightly exceeds baseline by tying parameters to the spending consequence.

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 concrete verb+resource: it identifies which contacts changed jobs and enqueues the JOB_CHANGE_DEPARTURE sequence for each mover. It explicitly distinguishes itself from enrichment ('An enrichment run is NOT this... it cannot notice a move'), so an agent can separate it from create_enrichment_run and create_job_change_run without opening a schema.

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?

Explicit when-not-to-use (enrichment) and explicit operational routing: 'IT RUNS ITSELF AND TAKES NO DISPATCH STEP... a dispatch_run after it makes the plan unexecutable.' It also warns that omitting filter_spec sweeps the whole book and charges for it. Alternatives and preconditions are named rather than implied.

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?

Dramatically exceeds annotation coverage, which only flags non-read-only and open-world. Discloses that firings run unattended, spend resources each time, require all step permissions, run under the caller's current permissions, stop on permission loss, and notify admins – critical safety context an agent cannot infer from annotations.

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 action, then groups cadence details, clearing behavior, and critical safety warnings in a logical flow. Every sentence carries essential information; no waste despite the length.

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?

Given no output schema exists, the description proactively explains the response ('when it fires and which steps ask the provider about their whole scope'). Covers all necessary prerequisites, failure modes, and side effects for an 8-parameter scheduling mutation.

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 schema has 100% description coverage, so baseline is 3. The description adds value by clarifying the IANA timezone default (UTC), the 'none' clear semantics, and the cadence-specific parameters. It doesn't add syntax beyond the schema, but reinforces key defaults and constraints.

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 ('Give a plan a schedule'), and explicitly covers the three operations: set, change, and clear. Clearly distinguishes itself from siblings like fire_plan (manual firing) and get_plan (reading).

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?

Tells the agent exactly when to use this tool with concrete conditions: only active plans can be scheduled, create-step plans refreshing nobody are refused, and it prompts reading the plan first. Also contrasts scheduled firing with manual firing, clarifying the alternative.

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 mark this as a non-read-only, non-destructive, closed-world mutation. The description goes further: it discloses partial-update semantics ('name only the inputs to change'), the derived-steps rebuild behavior, the refusal path for non-catalog plans, and explicitly rules out scheduling, firing or confirming side effects.

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?

Opens with the mutation and its coupling to steps, then the catalog precondition, then the partial-input rule, then the capability exclusions. Dense but front-loaded and free of filler; the enumerated input list is the only mildly heavy passage.

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?

No output schema exists, and the description covers the mutation model, validation/refusal behavior, and what is intentionally not done, which is most of what an agent needs. It could say more about the result of the rebuild or permission requirements, but nothing essential 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: the concrete Always On input names (scope, account_template_id, contact_template_id, account_credit_cap, contact_credit_cap, firing_cap) inside the otherwise generic 'inputs' object, plus the partial-name semantics.

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 (Change) and resource (an OUT-OF-THE-BOX plan's inputs, and with them its steps), and immediately distinguishes this from direct step editing, which it says never happens for catalog plans. An agent can tell this apart from set_plan_schedule, fire_plan and update_rule_template 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.

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

Gives a clear condition: the plan must be built from the catalog (managed true, with catalog_key and inputs, per get_plan) and is changed only this way; otherwise it is refused. It also states that only the named inputs change and the rest keep their values. It stops short of explicitly naming the sibling to use for scheduling/firing instead of this tool.

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