CRM Connector

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

Beyond the annotations, the description explains that the connector re-reads records, refuses records changed since the proposal, writes the rest, preserves undo where supported, refuses approval-required proposals, and is idempotent on repeat calls. These details give the agent concrete behavioral context for a destructive, idempotent write.

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 usage condition and scope, then adds only operational details that matter for safe invocation. Every sentence contributes useful guidance, with no obvious 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, idempotent write tool with an output schema, the description covers the important gaps: prerequisite approval, exact scope, concurrency refusal, undo behavior, approval-refusal behavior, and repeat-call semantics. An agent has enough information to invoke 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 single proposal_id parameter is already documented in the schema. The description reinforces that it applies one proposal returned by propose_changes 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?

The description states a specific action and resource: applying exactly one proposal's changes from propose_changes. It clearly distinguishes this from propose_changes by describing this tool as the write step that follows customer approval.

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

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

It explicitly says to use only after the customer saw the proposed changes and agreed. It also gives a when-not case: proposals needing the customer's own approval are refused here with an approve link.

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 the tool read-only, idempotent, non-destructive, and open-world. The description adds useful behavioral context about what is returned, including field-change semantics and optional expansions for fields, stages, and users, plus pagination by page.

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 usage warning is front-loaded, but the description is a dense, run-on paragraph with nested parentheticals that could be clearer. It also repeats some schema details, reducing 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 an output schema, full parameter descriptions, and annotations, the description provides enough context about purpose, alternatives, returned metadata, optional expansions, and pagination. Minor wording awkwardness keeps it from being fully 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 the schema already explains each parameter. The description reinforces the optional include values and field_names but mostly repeats the schema rather than adding new parameter 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?

The description clearly states the tool describes a record type in one answer, enumerating the returned metadata (CRM Connector fields and the system's own fields). It explicitly distinguishes the tool from reading records by naming search_records and get_record as alternatives.

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

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

It gives explicit timing ('Use before searching or changing records of one type') and an explicit exclusion ('Not for reading records'), routing the agent to search_records or get_record for that need.

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, idempotent, non-destructive, openWorld, so safety is covered. The description adds genuinely non-structured behavior: results are limited to the sync-linked systems, up to 50 records per call, and the return includes the record type each copy became in the other system. It stops short of discussing failure modes (unsynced record, partial links) or what happens when fewer than 50 are found.

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 usage trigger and packed with useful routing information, but the second sentence is long and clause-heavy, mixing return behavior, prerequisites, and the exclusion in a single breath. Slightly tighter segmentation would improve scanability; 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?

An output schema exists so return values need not be restated, and the description still flags the key return concept (the record type each became). Combined with the sync-link precondition and the get_record follow-up, an agent has everything needed to call this correctly 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 description coverage is 100%, so all three parameters are already documented in-schema (including the 'never pick one yourself' guidance for system). The description only reinforces the 50-record cap and the one-system scope, adding little 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?

The first clause names a specific verb and resource ('find the same records in the customer's other systems') and immediately contrasts it with the sibling list_related_records for intra-system links. An agent can distinguish this from get_record, search_records, and list_related_records 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 explicit when-to-use examples (won deals with no invoice, contact-to-customer mapping), an explicit exclusion ('Not for what a record is linked to inside one system (use list_related_records)'), and a prerequisite ('Only systems CRM Connector syncs with each other know their shared records'). It also routes the follow-up read to get_record.

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

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

Beyond the readOnly/idempotent annotations it discloses real behavior: no sign-in required, every answer carries a shareable setup link, unsupported systems should be answered with a prefilled request URL, and spreadsheet sources additionally return a template with download link, tabs and columns. The one weakness is that its enumerated 'supported today' list (22 systems) is far shorter than the schema enum (63), so an agent is told to declare enum-valid systems like airtable unsupported without any explanation of that gap.

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

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

The routing and behavioral content is front-loaded and dense, but the flat enumeration of ~22 supported systems duplicates the schema enum and pushes the prose past a reasonable length, and its divergence from the enum makes the bulk actively confusing rather than merely 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?

With an output schema present, the description needn't document return values, and it covers invocation modes and the request-form fallback thoroughly. It leaves one unresolved case: what an agent should do when a value is valid per the enum but absent from the stated supported list.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine semantics the schema lacks: zero systems names both products, one system lists every partner plus what travels, two systems detail that specific pair, and a spreadsheet source triggers extra template output. Only the system-key vocabulary is restated rather than 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?

Opens with a concrete resource (integrations between two systems) and states exactly what the tool answers: what CRM Connector supports, which systems pair with which, and what travels (record types, direction, trigger events, ready rules). It is clearly separable from siblings like plan_integration or get_field_details, and the name is not merely restated.

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 routes the agent: "Not for setting up an integration with chosen record types (use plan_integration), for which fields travel (use get_field_details), for how to connect a system (use get_connection_guide), for a person's own integrations or sync results." It also gives a fallback script for unsupported systems, which is unambiguous when-to-use 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral facts: it works without sign-in, for a signed-in account it additionally returns enabled systems plus setup links, it names no monetary amounts, and it lists what the product never does. That is substantial context an agent cannot infer from 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 core content is useful and mostly front-loaded, but it is delivered as one very long run-on sentence dense with parenthetical asides, making it harder to scan than a 3-4 sentence structure would be. Several clauses (package approval mechanics, setup flow) could be tightened 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?

For a zero-parameter informational tool with an output schema, the description covers the trigger, the content returned, the account-state variation, the pricing silence, the auth requirement, and the follow-up action. Nothing an agent needs in order to decide to call it, or to interpret the answer to the user, is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description reinforces this implicitly by stating it needs no sign-in and behaves differently based on account state rather than arguments, which is the relevant semantic nuance for a no-arg call.

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?

It states specifically that the tool explains what AI Agents does, its two packages (AI Analyst vs AI Agent), what it never does, and how a system gets enabled, which is far beyond restating the name. It also carves out what it is not (record syncing = an integration) and names find_sync_options. The only deduction is that the purpose sentence is buried mid-paragraph inside a run-on first sentence that mixes purpose with usage triggers.

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 trigger conditions (someone asks about connecting a business system to ChatGPT/Claude, automations, or 'AI Agents'), an explicit exclusion (not for syncing between systems — use find_sync_options), and an explicit next-step alternative (use send_request with kind ai_access once the person confirms). It even states no sign-in is needed, removing a common blocker to calling it.

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, idempotentHint=true, openWorldHint=false, so the safety profile is covered. The description adds genuinely non-redundant context: it is informational only ('It needs no sign in', 'to connect anything: the person connects in CRM Connector itself') and previews what the answer contains (method, steps, fields with locations, setup link).

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 question-list are front-loaded and every sentence carries information. Some sentences are long and clause-stacked ('whether connecting means signing in or pasting a key... every field asked for with where to find it in that system'), which slightly hurts scannability but not correctness.

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?

An output schema exists, so return values need not be documented, yet the description still summarizes the response shape well enough to set expectations. For a two-param, read-only lookup tool with full schema coverage and annotations, 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 params are enums, so the baseline is 3. The description earns above baseline by explaining the non-obvious conditional use of other_system: only meaningful for googlesheets/spreadsheetfile, where it returns a purpose-built template with a download link — behavior the schema description only partly conveys.

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 (integration connection guides) and enumerates the exact questions it answers — how to connect, what credentials are needed, where to find them, sign-in vs. key. It explicitly distinguishes itself from find_sync_options, so an agent can separate it from the nearest sibling 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?

Both inclusion ('Use when someone asks how to connect a system...') and exclusion ('Not for what travels between two systems (use find_sync_options) or to connect anything: the person connects in CRM Connector itself') are spelled out with the named alternative. The spreadsheet special case adds a concrete routing rule for other_system.

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 read-only, idempotent, non-destructive behavior, but the description adds substantial context beyond them: it explains the possible travel modes ('always', 'needed', 'switchable'), notes such as fields that only travel on record creation, the fields that do not travel, a setup link, and that no sign-in is needed. This is rich behavioral disclosure that helps an agent interpret results correctly.

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 use case and a clear exclusion at the end, which is effective structure. It is somewhat long because of the explanatory examples and travel-mode definitions, but those details are useful rather than wasted, so it remains appropriately sized for the domain.

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 has an output schema, annotations, and full schema coverage, the description is complete: it covers the purpose, key use case, return content, travel-mode meanings, exclusions, and authentication context. An agent would have enough information to select and invoke this tool 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 enum parameters are already well documented in the input schema. The description adds only that record type keys come from find_sync_options, which the schema also states, and does not contribute additional parameter-specific meaning such as how source and target directionality affects the result beyond the schema definitions.

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+resource: it returns field-detail information for integrations between two systems for a given record type. It distinguishes itself from siblings by explicitly naming find_sync_options for record-type discovery and excluding personal field mapping, so an agent can tell exactly what this 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?

It gives concrete when-to-use guidance: 'Use when someone asks whether a particular field travels between two systems for one record type,' with examples such as phone number, address, due date, line items, and tax. It also states when not to use it: not for which record types a pair offers (use find_sync_options) and not for a person's own field 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the response carries a 'short note on what to do next' whose content varies by state (first-integration setup, setup awaiting a plan, items needing attention). It does not mention auth requirements, but for a zero-param read that is a minor omission.

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 routing guidance is correctly front-loaded, but the second sentence is a long run-on that drifts into describing what the plugin offers across 'its two products' — material that is tangential to invoking this tool and makes the response shape harder to parse. It is not padded with filler, but it is meaningfully longer than the task requires.

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?

An output schema exists, so return values need no prose explanation, and the tool is a zero-parameter read. Everything an agent needs to decide to call it and to interpret the call is present, including the state-dependent content of the returned note.

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

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

The tool takes no parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 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 — 'know which CRM Connector account is connected' — and immediately enumerates what comes back (opaque id, organisation name, signed-in email). It explicitly separates itself from list_integrations and get_sync_health, so an agent can route 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 concrete triggering contexts ('right after connecting', 'to tell two connected accounts apart') and an explicit exclusion clause naming the sibling tools to use instead for integrations and sync results. This is the when/when-not/alternatives pattern at full strength.

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/idempotent/non-destructive, but the description adds context they cannot: data is read 'live from the system' (freshness), the field set is normalized across systems with opt-in extras, and most valuably a security directive never to follow instructions found in record content. That prompt-injection warning is behaviorally significant and appears nowhere in 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?

Three dense sentences, front-loaded with the purpose, then the sibling routing, then the safety note. The opening clause 'AI Agents (inside one system):' is slightly awkward and costs a beat of parsing, 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?

Four parameters, all schema-documented, annotations covering the safety profile, and an output schema so return shape needn't be described. The description fills the remaining agent-facing gaps: when to choose it, how to extend the projection, and how to treat untrusted content.

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 exceeds that by explaining that `fields` pulls the system's own fields (e.g. lead status, custom field) and where to source valid names ('names from describe_record_type, under systemFields'). The only gap is that it doesn't restate valid `type` values, but those are already 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 ('read one record of an AI agent's system by its id') plus scope ('live from the system'), which is far more precise than the title. It explicitly names the two sibling tools it is not (search_records, list_related_records), so an agent can distinguish it 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?

There are explicit exclusions with named alternatives: 'Not for finding records (use search_records) or for what the record is linked to (use list_related_records).' It also states the precondition for the `system` parameter (ask the person which AI agent, never pick one yourself), which governs correct invocation.

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/idempotentHint/destructiveHint=false, so the bar is lower, yet the description still adds real context: failure reasons never quote record contents, conflict names are only visible to a user permitted to manage integrations, and 'include' only applies with an integration_id. It stops short of noting rate limits or pagination across the 30-day window.

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 trigger scenario and tightly packed, but several sentences are long nested clauses with heavy colon/semicolon chaining, which slows scanning. Every sentence does carry information, so the length is earned, just not optimally structured.

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?

Output schema exists so return values need not be spelled out, yet the description still characterizes the payload (failures grouped by reason with counts per integration and record type, waiting records, totals, conflicts). With four optional params, permission caveats and explicit exclusions covered, 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 the baseline is 3, but the description goes further by explaining what each optional parameter unlocks (recent_syncs adds moment/outcome plus per-record-type read/written/skipped/failed counts; conflicts adds waiting conflicts) and by stating that integration_id is required for include to have effect.

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 ('get_sync_health' / integrations sync status) and immediately frames the caller scenario ('a signed in CRM Connector customer asks how their syncs are doing'). It also distinguishes itself from siblings by naming list_integrations, resolve_conflict and run_sync as the wrong tools for adjacent jobs.

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 (questions about failures, missing records, waiting items, last run, pending conflicts), explicit when-not ('Not for listing integrations', 'not for fixing anything'), and explicit routing to the alternatives with the condition that selects each. 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?

Annotations already cover read-only/idempotent safety, but the description adds substantive behavior: nothing is self-serve, provisioning is quoted and set up per account, the customer then signs in and picks a package, and the empty-list case returns whether one is enabled versus awaiting setup. That is genuine context an agent cannot derive from 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?

Purpose is front-loaded in the first sentence, and the provisioning/empty-state/fallback details all serve an invocation decision. It runs long and could tighten the package explanation and URL, but no sentence is pure 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?

An output schema exists, yet the description still gives enough behavioral and edge-case coverage (not-connected case, missing-system case, next tool to call) for an agent to act correctly. Nothing material to calling or interpreting 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?

The tool takes zero parameters, so the 4 baseline applies; the schema has nothing to explain. The description adds value by noting the returned id is what every other record tool, including list_automations and propose_automation, consumes — though that is return-value semantics rather than parameter 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?

Opens with a specific verb and resource ('List systems connected to AI Agents') and immediately scopes it to a signed-in CRM Connector customer's own business systems. It states what is returned (id, package, per-record-type permissions) so it is clearly distinguishable from record-reading 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?

Explicitly says 'Use first when a signed in CRM Connector customer asks about the records in their own business systems', and gives a fallback path when a system is absent (say so, then send_request with kind ai_access or share the request URL). When-to-use, when-not-in-list, and the alternative are all 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 already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds useful non-obvious context: the status vocabulary (proposed/active/paused), the 30-day run-count window, why-paused reason, and the approval link for rules awaiting customer action. Return-shape detail is partly redundant with the output schema, keeping it just 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?

Front-loads the trigger condition and packs the alternative-tool exclusion at the end, with no filler sentences. The middle sentence is a long run-on enumeration of return fields that could be tightened, but every element is informative.

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?

One optional parameter fully documented in the schema, an output schema covering return values, and annotations covering safety — the description fills the remaining gaps (trigger intents, sibling exclusion, status vocabulary). 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 description coverage is 100% and the single parameter is optional, so the schema already carries the semantics. The description's 'Leave the system out for every system' restates what the schema says ('Leave it out for all of them'), adding no new syntax or format information.

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 automations) and enumerates the concrete customer intents it serves: which automations run, whether a rule ran, or finding one to pause/resume/change/remove. It explicitly distinguishes itself from the closest sibling ('Not for the changes the assistant made (use list_changes)').

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 trigger conditions ('Use when the customer asks...'), a scoping rule ('Leave the system out for every system'), and names the alternative tool plus the condition that selects it (list_changes for assistant-made changes). Nothing about when to pick this tool 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds useful context about what is returned: newest proposed, applied, failed, and undone changes, each with before/after values and an id. It does not discuss pagination or ordering mechanics in depth, but the output schema and limit parameter handle that.

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

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

Three tight sentences: purpose and trigger first, return contents second, exclusion last. Every sentence adds distinct value, and there is no repetition of annotation or schema content.

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-only list tool with full schema coverage, an output schema, and rich annotations, the description covers purpose, triggers, exclusions, and return shape. 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 coverage is 100%, and both parameters are fully described in the schema. The description does not add syntax or selection guidance beyond the schema, such as how 'system' interacts with the agent scoping. Baseline 3 is appropriate when the schema carries parameter meaning.

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 ('list ... changes') and names the exact scope: the AI agent's changes inside one system. It also explicitly distinguishes itself from the closest lookalike sibling by saying it is not for automation rules and pointing to list_automations.

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 triggering situations ('what the assistant changed' and 'find a change to undo') plus an explicit exclusion with the alternative tool named. Little is left for the agent to infer about when to select this tool versus list_automations.

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, idempotentHint and destructiveHint=false, so the safety profile is covered; the description nonetheless reinforces 'it only reads' and adds the genuine prerequisite that the caller be signed in. It also describes the return payload's fields (id, systems, direction, status, record types, last sync, 7-day failure/waiting counts), which the annotations do not say.

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 scope, then routing, then return shape; every clause carries information. The second sentence is a long enumeration of return fields that could be tightened, but nothing is wasted or 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?

Covers everything an agent needs for a zero-param read tool: scope, auth prerequisite, sibling disambiguation, and the shape of the result (an output schema exists, so the field list is a bonus rather than the only source). 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?

Zero parameters, so the schema imposes nothing and the baseline is 4. The description correctly signals that this is an unfiltered 'my integrations' call with no system argument, implicitly contrasting with find_sync_options which takes one.

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 (list) plus resource (integrations) with the disambiguation '(between two systems)'. It also enumerates the exact questions it answers (which were set up, whether running, last sync), which distinguishes it cleanly from find_sync_options and get_sync_health.

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

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

Explicitly states when to use it ('when a signed in CRM Connector customer asks about their own integrations, and only then') and names three alternatives with the conditions that select them: find_sync_options (without a system, no sign in), get_sync_health (why records failed), and set_integration_status (to change one). No inference required.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by scoping results to a single named system and by clarifying that only links/metadata are returned rather than the activities' contents. It stops short of describing result shape or page-size defaults, though the output schema and cursor/limit params carry that.

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

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

Three tight sentences with the scope qualifier '('inside one system')' front-loaded, followed by use/not-use routing. Dense but every clause earns its place; the opening 'AI Agents (inside one system)' label is slightly awkward phrasing but functionally front-loads the key scoping fact.

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?

An output schema exists, all six parameters are documented, and the description covers purpose, exclusions and the correct sibling for each adjacent need. What remains unstated — pagination behavior and the exact shape of a linked-record entry — is already handled by the cursor/limit fields and the output schema, so 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 the schema already documents id, type, related, limit, cursor and system. The description adds only the framing of 'inside an AI agent's system' and illustrative pairings (contact→deals, deal→notes), which slightly clarify the type/related pairing but give no additional format or constraint detail. 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 what a record is linked to') and enumerates the related categories (records of another type, notes, tasks, calls, meetings, emails) with concrete examples ('deals of a contact', 'notes of a deal'). It also explicitly names the sibling it is not (find_linked_records) and the content-reading sibling (read_activities), so it is distinguishable 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 an explicit when-to-use ('see which records ... one record is linked to inside an AI agent's system'), an explicit when-not with the alternative to use instead ('Not for the same record in the other connected systems (use find_linked_records)'), and a further routing rule to read_activities for the content itself. The system parameter's guardrail ('ask the person which AI agent they mean ... never pick one yourself') reinforces correct invocation.

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/idempotent annotations it discloses the crucial behavior that 'nothing is created by this tool' and that the person signs in, connects and reviews before anything syncs. It also explains the asymmetric both_ways outcome and that the answer names which record types stay one way and why.

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 use case and constraints before the mechanics, and nearly every sentence earns its place. There is mild duplication: the one-way/both_ways behavior is restated in the description and again in the direction parameter schema, costing a little tightness.

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 planning tool with an output schema, the description covers the input intent, the no-side-effect contract, the prerequisite workflow, and the shape of the result (what travels, which direction, prefilled link). An agent has everything needed to call it and set expectations.

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 real meaning by stating the default is one-way and that both_ways only applies to record types the pair actually carries both ways, with leftovers reported in the answer. It does not add anything about source_system/target_system keys beyond the enum, and trigger semantics 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+resource ('Integrations between two systems' / 'It plans...') and concretely describes the artifacts produced: record types that travel, direction, and a prefilled wizard link. It explicitly distinguishes itself from find_sync_options and list_integrations, so an agent can route between 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?

Gives explicit when-to-use examples ('when a deal is won in our CRM, make a draft invoice...'), a prerequisite ('Call find_sync_options first when you do not know which record types a pair offers'), and explicit exclusions ('Not for questions about what is possible... or for a person's own integrations'). This is textbook when/when-not/alternatives 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?

The description adds rich process detail, but it directly conflicts with the destructiveHint=true annotation by stating “Nothing runs yet” and that the rule only starts after customer approval. It also says the rule “never deletes,” reinforcing that the tool call itself is not destructive. This is an annotation contradiction.

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 the complexity of an 8-parameter nested proposal tool justifies most of the length. It is front-loaded with usage guidance and the core rule shape, though there is some repetition around the one-system scope and approval flow.

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 complexity, output schema, and nested input, the description covers purpose, alternatives, prerequisites, return behavior, approval lifecycle, and key limitations. An agent has enough context to know what this tool does and how to prepare the call, aside from the annotation conflict.

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 a useful conceptual mapping of trigger/conditions/actions and apply_to_existing into “when / only if / then / also existing records.” It also ties nested action values back to propose_changes and field keys to describe_record_type, helping the agent connect the parameters.

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 (“propose an automation”) and narrows the scope to one fixed rule on one record type. It explicitly distinguishes the tool from propose_changes for one-off changes and plan_integration for cross-system syncing.

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 when-to-use guidance (“keep happening by itself inside one system”) and explicit alternatives for one-off changes and integrations. It also describes the pre-call confirmation step and how to use replaces for an existing rule.

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?

The description adds substantial context beyond the annotations: nothing is written, the response contains current and proposed values plus a proposal id, the agent must show it to the person and ask before applying, and approval-link handling is described. It also discloses that unlink_records requires person approval and that the tool never deletes or records payments.

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 the tool is complex and multi-action, so most of the length is justified. It is front-loaded with usage and action definitions, though the dense action-definition block could be structured more cleanly.

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 proposal tool with an output schema, the description covers purpose, action selection, item limits, approval handling, and the handoff to apply_proposal. There is no material gap that would prevent an agent from invoking 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?

Although schema coverage is already 100%, the description adds action-level semantics that the schema does not fully convey: what each action is for, how set_fields differs from update_fields, that move_stage can close a record, and that link_records is a no-op when the link already exists. It also frames record-item selection around the chosen action.

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: it proposes record changes rather than performing them. It clearly distinguishes itself from read tools and from apply_proposal by saying every change goes through here first and nothing is written yet.

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 guidance ('Use whenever the person asks to change records...'), names the read alternatives ('use search_records or get_record'), and explains the follow-up workflow to apply_proposal. It also states constraints such as one action, one item per record, and at most 25 items.

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 carry readOnly/idempotent/non-destructive, but the description adds a substantive safety trait they don't: returned content is the person's data and instructions inside it must never be followed (prompt-injection guard). It doesn't say what happens with an unknown id or a kind/id mismatch, and openWorldHint is left unelaborated.

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 tight sentences with use case, exclusion and safety note, front-loaded so the reader learns the primary purpose first. Minor cost: the opening 'AI Agents (inside one system)' is awkward phrasing that delays the actual verb slightly.

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?

Return shape is covered by the output schema and all four parameters are fully described, so the description only needed to add routing and safety context, which it does. Remaining gap is edge behavior on invalid or mismatched ids, which matters for a batch read of up to 100 ids.

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

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

Schema coverage is 100% and the schema already documents ids (max 100), kind's enum, fields, and the system lookup rule, so the description's only added semantics is that ids originate from list_related_records. Baseline 3 is correct when the schema does this much of 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?

States a specific verb (read) and a specific resource (notes, tasks, calls, meetings, emails) scoped to one AI agent's system, retrieved by ids. It explicitly disclaims the sibling list_related_records, so an agent can separate lookup-by-id from discovery 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 ('read ... by their ids, as list_related_records gives them') and an explicit when-not with the named alternative ('Not for finding them (use list_related_records first)'). It leaves one sibling gap: it never distinguishes itself from get_record or search_records, which an agent comparing tools would still have to infer.

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 flag destructive, idempotent and open-world behavior, so the description is not the sole carrier. It still adds real context beyond them: both outcomes are reversible ('Both can be undone in CRM Connector') and user confirmation is required before invoking. It does not describe what 'keep_apart' does to future sync attempts beyond 'stops asking', which is a minor gap.

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

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

It is short in total length, but the middle sentence is a dense run-on that packs the semantics of both enum values, the undo behavior and the confirmation rule together. Front-loading the get_sync_health dependency is good, but structure could be much tighter.

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 an output schema present, return values need no explanation, and all parameters are schema-documented. The description supplies the missing operational context: prerequisite, confirmation, and undoability. Only the precise semantics of 'keep_apart' going forward is left ambiguous.

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 and the enum values. The description attempts to add meaning to the 'choice' enum, but the explanation of 'sync' is barely parseable, so it adds little usable semantics over 'sync or keep_apart'.

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 action (resolving a sync conflict) and scopes it to integrations between two systems, and it explains the outcome of each choice. It is distinguishable from siblings like get_sync_health or run_sync. However, the phrasing of the 'sync' outcome ('the record that also matches the one the shared record follows from the next sync') is convoluted and forces the agent to re-read.

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 sequencing ('Use after get_sync_health with include conflicts') and a precondition ('once the person chose'), plus a confirmation requirement ('Ask the person to confirm first'). It does not name a competing alternative tool, but the when-to-use context is clear.

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 the tool as non-read-only, open-world, non-idempotent, and destructive; the description adds crucial context beyond that. It explains what mode full does, that it rewrites every record without duplicates to repair failed records, that it takes longer, that confirmation is required, and that a sync starts at most once every 15 minutes per integration.

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: it begins with the resource, then the use condition, then mode behavior, confirmation, id source, rate limit, and the excluded use case. Every sentence carries actionable information with no filler.

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

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

With annotations and an output schema already present, the description still covers the full decision context: when to use it, how the modes differ, confirmation needs, required id source, rate limit, and the alternative for sync results. Nothing essential 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 coverage is 100%, so the baseline is 3, but the description adds real meaning for the mode parameter by contrasting changes with full and describing the repair behavior and longer runtime. The integration_id guidance mostly reinforces the schema rather than adding new detail.

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: sync an integration now. It distinguishes this from the sibling get_sync_health by explicitly saying it is not for checking what a sync did.

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 names the exact situation for use: a signed-in CRM Connector customer wants an integration to sync now, for example after fixing failed records. It also explains the two modes, when to confirm with the person, where to get the integration id, the 15-minute rate limit, and which sibling to use instead for sync results.

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 readOnly/idempotent/openWorld annotations, the description discloses pagination semantics, mutual exclusivity of text and field, that fields controls which columns come back, and a prompt-injection safety warning about record content. It also flags the authorization/identification requirement for the system parameter.

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, and every clause carries information (modes, exclusions, safety). It is dense to the point of being a single long sentence with stacked parentheticals, 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?

For a 9-parameter, open-world search tool with an output schema and safe-read annotations, the description covers modes, paging, alternatives, and the data-trust warning. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so this is baseline 3 or better; the description adds real meaning by grouping parameters into two mutually exclusive query strategies and clarifying that text is interpreted as the system's own search syntax. It does not add much on operator/cursor semantics 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 ('find records of one type in an AI agent's system, page by page') and immediately names the siblings it is not: get_record for single-id lookup and find_linked_records for the same record across other systems. The scope is unambiguous.

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

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

Explicitly describes the two search modes (text-based system search vs. field/operator/value), tells when to omit text (page through all), and states two exclusions with named alternatives. It also adds a procedural rule: ask the person which AI agent they mean and never pick one yourself.

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 that this is a non-read-only, non-destructive, non-idempotent write action. The description adds important behavior beyond annotations: no sign-in is required because the signed-in account email may be used, the person must confirm exactly what will be sent, the setup may be quoted, and CRM Connector answers by email usually within one working day.

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 purpose and usage trigger are front-loaded, and the dense detail reflects a multi-step request workflow with nine parameters. It is somewhat long and runs several clauses together, but most sentences carry actionable information rather than repetition.

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 complexity, nine parameters, and an output schema, the description covers the important non-schema context an agent needs: confirmation before sending, sign-in versus email handling, request kinds, AI Agents setup process, expected email response, and form alternatives.

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 parameters. The description still adds useful semantic context beyond the schema, such as omitting email when the person is signed in, using read for AI Analyst and read_write for AI Agent, and passing a budget only when the person named one.

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: send a request to CRM Connector for either an integration or AI Agents setup. It distinguishes the two request kinds clearly and explicitly names get_ai_agents_info as the sibling that explains the AI Agents distinction.

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 the tool: when the person wants something CRM Connector does not yet offer, either an integration or AI Agents. It also gives prerequisites and alternatives, including showing the request for confirmation, handling sign-in/email, and pointing to the form-based request pages.

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 idempotentHint=true, but the description adds what those hints cannot: remove is permanent but nothing is deleted from the system, all prior changes stay in the change log with undo, and resuming a never-approved rule returns its approval link instead of activating it. That last detail is a genuine behavioral surprise the agent could not infer 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 usage trigger, then prerequisites, then the alternative. Dense but nearly every clause carries new information; the multi-clause sentence about resume and approval links is a little hard to parse on first read.

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

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

For a destructive state-change tool with an output schema present, the description covers when to call, confirmation gating, prerequisites, per-command effects, reversibility, and the sibling alternative. Nothing an agent needs to invoke it safely 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 goes further by spelling out the effect of each enum value (pause halts until resumed, resume reactivates, remove is final) rather than repeating the bare enum. It does not add id format or length details beyond what 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 specific verbs and the exact resource: pause, resume or remove one automation. It also draws a sharp boundary against the sibling that changes rule behavior (propose_automation with replaces), so the agent can route 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 trigger ('Use when the customer asks to pause, resume or remove one automation, after they confirmed'), explicit prerequisite ('Needs the id from list_automations'), and an explicit exclusion with the alternative named ('Not for changing what a rule does (use propose_automation with replaces)').

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 past the annotations by describing the refusal path (resume rejected when a connection needs re-auth or the plan has no room) and instructing the agent to relay that refusal verbatim. Also clarifies that pause is non-destructive, which meaningfully refines the blunt destructiveHint=true flag without contradicting 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?

Front-loads the resource and the trigger phrase, and every sentence carries operational content. The nested parentheses make a couple of sentences denser than necessary, but 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?

An output schema exists, so return values need no explanation; the description spends its space on what the agent must do (confirm, look up id, relay refusals) instead. Nothing needed to call this two-parameter mutation 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 3 baseline applies, but the description adds real semantic weight to `status` by explaining that resuming also switches on a draft once the account has a plan — something the enum text does not say. It also reinforces the id's provenance from list_integrations.

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?

Names the resource (integrations between two systems) and the two concrete actions (pause: nothing syncs, nothing deleted; resume: status active, which also activates a draft when a plan exists). A reader can distinguish it from set_automation_status and from deletion, which the description explicitly says happens elsewhere.

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?

States the caller condition (a signed-in CRM Connector customer wants a pause or resume), an explicit prerequisite flow (confirm first, get the id from list_integrations), and an explicit exclusion (permanent removal happens on the integration's page in CRM Connector). This is when/when-not/alternative coverage in four sentences.

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 flag destructiveHint and idempotentHint, but the description adds the crucial conditional-guard behavior: the revert only applies while the record still holds what was written, so newer work is never overwritten. It also discloses that new records cannot be undone and that nothing is deleted, which materially shapes agent expectations.

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

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

Four compact sentences, zero redundancy, and the trigger condition is front-loaded before the behavioral caveats and the sibling exclusion. The 'AI Agents (inside one system)' scoping prefix reads slightly awkwardly but still earns its place as a caller constraint.

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?

Output schema exists so return values need no explanation, and the single parameter is fully documented. What remains — safety guard, irreversibility of new records, confirmation requirement, and alternative tool for automations — is all present, leaving no gap an agent would need to guess at.

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 change_id description already names its sources (apply_proposal, list_changes), so the schema carries the parameter burden. The tool description adds only the implicit notion of a 'change' being the unit of undo; it contributes nothing beyond baseline for this single parameter.

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 — undo a change the assistant made — and immediately qualifies scope ('values from before back'). It is clearly distinguishable from sibling mutations like set_automation_status or apply_proposal.

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 the customer asks to undo a change the assistant made'), explicit when-not with the named alternative ('Not for stopping an automation (use set_automation_status)'), and a procedural prerequisite ('Ask the customer before calling it').

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