Capable

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the mutation profile is known. The description adds real behavioral value beyond that: the at-most-one primary champion invariant and that setting it auto-clears any previous primary. What it doesn't disclose is the destructive side of overwriting an existing link (e.g. what happens to a prior role/notes on re-link), which for a destructive-hinted tool would be worth one sentence.

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 side effect, then cleanly sectioned into 'When to use' and 'Example'. Slightly redundant where the seed role values are repeated verbatim from the role parameter's schema 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?

An output schema exists, so return values need no explanation. For a 5-param mutation the description covers the action, the uniqueness invariant, id resolution preconditions, terminology vs. opportunity_contacts, and a worked example — 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 baseline is 3, but the description adds semantics the schema does not: it names the seed role vocabulary and explains the uniqueness/auto-clear rule for is_primary_champion, which is a constraint rather than a type. The role list is somewhat duplicated from the schema, which caps it below 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 ('Link a contact to an account with a role') and explicitly distinguishes itself from the opportunity_contacts concept, which is the most likely confusion point. An agent can tell what this creates and where it lives 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?

Explicit 'When to use: When you learn someone's role at a customer', plus the qualifier for is_primary_champion, plus a precondition ('Resolve account_id + contact_id with search_* first — never invent ids'). It also supplies a concrete example, 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 declare this is a non-read-only, non-destructive, non-idempotent write, so the bar is lower. The description still adds useful lifecycle facts beyond them: notes are searchable and soft-deleted (i.e. recoverable), and the created note is returned. It omits any permission or visibility model for shared records.

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 required-linkage constraint before the usage note and example, and every block carries information. The example sentence is somewhat long, but it concretely illustrates the expected free-form content, so it 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?

With annotations covering the safety profile and an output schema present, the description covers the remaining agent-relevant questions: required linkage, searchability, soft-delete semantics, and return behavior. Only secondary details (permissions/visibility, size or rate limits on the note body) are absent.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds a genuine cross-parameter rule the schema does not encode: 'MUST link to at least one' of the four polymorphic id fields, each of which is documented only as 'A uuid.' It adds the cardinality constraint but no guidance on how the target type affects behavior.

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 gives a specific verb+resource ('Attach a free-form note to any record') plus the accepted target types (account/contact/opportunity/touch), the key linkage constraint, and the return value. It is clear enough to distinguish it from structured writers like create_record, but it never names a sibling it is not (e.g. log_touch), so it stops short of full sibling differentiation.

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?

'When to use: Free-form context that doesn't fit a structured field' gives a clear positive selection criterion distinguishing it from structured-field mutations. It does not, however, state when NOT to use it or point at alternatives (log_touch, update_record) that an agent might otherwise reach for.

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 annotations (idempotentHint, destructiveHint=false), the description discloses admin-only authorization, the idempotency mechanism ('existing keys are skipped', so no duplication on overlap), unknown-key handling ('did-you-mean'), and the return payload. 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?

Well front-loaded and appropriately scoped, but idempotency is stated twice ('Idempotent: existing keys are skipped' and again in When-to-use as 're-applying only adds what's missing'), a minor redundancy in an otherwise tight 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?

An output schema exists, so return values need only a passing mention, which is given. Authorization, idempotency, error behavior, and the key-discovery path are all covered, leaving nothing an agent needs in order 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 terse schema baseline would be 3, but the description adds real navigation value: it tells the agent the key comes from describe_schema's `templates` section, gives examples (account_hierarchy, quoting), and states unknown-key behavior.

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 ('Apply a curated schema template') and immediately characterizes the resource as 'a pre-vetted bundle of objects, fields, pick-list values, pipelines and starter views.' This clearly distinguishes it from the many define_*/archive_* siblings that operate on single pieces.

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 'When to use' section explicitly frames the case ('adopt a whole curated bundle at once ... instead of defining each piece'), routing the agent away from the granular define_* siblings. It also gives a concrete example (quoting).

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 (which already flag destructiveHint/idempotentHint/openWorldHint): it specifies that the first call is a no-op returning {cancelled:false, requires_confirm:true}, that every tentative hold and the booked event are released from every host's calendar, that a booked invitee receives a cancellation email, and that the action is irreversible.

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 critical destructive/two-step warning, but the same content is duplicated: the two-step process is explained in the opening paragraph and again under "When to use," and the cancellation-email behavior appears twice. The redundancy dilutes an otherwise well-structured 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?

An output schema exists, so return details need not be spelled out, and the description still covers the destructive profile, the confirmation protocol, the calendar side effects, and irreversibility. Nothing an agent needs to call this 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 meeting_id, reason, and confirm's confirmation semantics. The description reinforces the two-step confirm workflow but largely repeats what the confirm field description already states, adding little new 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?

States a specific verb and resource ("Cancel a meeting") with an unambiguous scope, plus the destructive, two-step nature. An agent can immediately distinguish it from siblings like reschedule_meeting, propose_meeting, or record_meeting 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 clear context ("When to use: When plans change") and a concrete workflow for the confirm step, plus the fallback guidance "re-propose to start over." However it never names alternatives explicitly (e.g., reschedule_meeting for changes that aren't cancellations), so routing relies on 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 declare destructiveHint=true, but the description goes well beyond that: it specifies the exact field mutations, the audit event written, the ARR rollup impact, the returned lifecycle suggestion, and the two-step confirm protocol ('confirm with the user first, then call again with confirm: true'). This is precisely the context an agent needs to avoid an irreversible mistake.

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 action and side effects, then separates 'When to use' and an example. Nearly every sentence earns its place; the example adds marginal value over the when-to-use line, which keeps it just short of ideal density.

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 mutation with an output schema present, the description covers effects, confirmation protocol, required inputs, and follow-up guidance. 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 baseline is 3, but the description adds real meaning: it explains why cancellation_category matters (retention analysis) and clarifies confirm's role as a two-phase confirmation gate, which the schema reduces to 'Boolean (true/false)'. It also implicitly disambiguates reason vs. category, though that distinction is already carried by 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+resource ('Cancel a subscription') and immediately enumerates the exact state written (status='canceled', canceled_at, cancellation_category, cancellation_reason). The side-effect list (subscription_events row with negative mrr_delta, account.current_arr_cents drop) distinguishes it clearly from siblings like renew_subscription, update_record, or delete_record.

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?

'When to use: Customer cancellation' plus a worked example (Acme consolidating to a competitor) gives clear invocation context, and it directs the agent to always supply cancellation_category. It stops short of naming alternatives or when-not conditions (e.g., renew_subscription or restore_record), so it is clear but not exhaustive.

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 by explaining that the first confirmation freezes the selection, that only an identical receipt/key/selection replays stored outcomes, and that expiry blocks first commits but not exact replays. It also discloses dependency ordering, guard application, and required handling for execution_in_progress versus execution_state_unknown.

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 save action and behavior, then provides a 'When to use' section and example. The density is justified by the tool's complexity, though several semicolon-chained clauses and vague lines like 'Report saved/unsaved rows truthfully' reduce readability.

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 destructive, idempotent commit nature of the tool, the description covers replay, expiry, idle/error states, dependency blocking, guards, and success acknowledgement. With an output schema and full input schema descriptions already present, this is complete 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 schema already documents all four parameters, including confirm, receipt, idempotency_key, and selected_proposal_ids. The description reinforces the approved-selection and idempotency semantics but adds little parameter-level detail beyond the schema's own 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 and resource: 'Save only the explicitly approved review selection.' It distinguishes the operation from prose review and status tools by scoping the write to an already-approved receipt and selection, so an agent knows exactly what this commits.

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: After explicit app or chat approval' and 'reuse the exact request to read stored results.' It also rules out alternatives: no fresh reviews on execution_state_unknown and never automatic write retries.

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=false, destructive=false, idempotent=false), and the description substantially exceeds that. It discloses that the server snapshots catalog prices and computes totals, that out-of-cap discounts and out-of-tier bundle quantities are flagged rather than blocked, that bundles expand and inherit line discounts, and that status draft/sent records a pre-commit artifact.

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 constraint (never pass a price; server computes lines/totals) is front-loaded and most of the density is load-bearing pricing semantics. The pricing_mode clauses are somewhat compressed into run-on phrasing, costing a bit of readability, but no sentence 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?

With an output schema present, the description needn't detail return values, yet it still summarizes them ('the quote, priced lines and flags'). For a non-idempotent mutation with 8 parameters and nested line objects, the description covers the behavioral and pricing rules 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 coverage is 100%, so the baseline would be 3, but the description adds real semantics the schema lacks: it forbids passing money amounts, explains that discounts are percentages at both line and quote level, and clarifies pricing_mode behavior (per_unit multiplies, flat charges once, missing/unknown means flat). The only gap is that it never explains opportunity_id or valid_until, which the schema covers only shallowly.

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 ('Draft a quote for an account') plus the input basis ('catalog product IDs and quantities'), and it explicitly bounds the scope by saying invoicing and contracts happen elsewhere. An agent can tell this apart from update_quote and from generic record creation 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?

There is an explicit 'When to use' line ('The user asks for a customer quotation') plus a concrete example, which is clear context for selection. It stops short of naming exclusions or the sibling to use for editing an existing quote (update_quote), so it is not a full when/when-not treatment.

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=false, destructive=false, openWorld=true, and idempotent=false. The description adds meaningful behavior beyond annotations: sequence plans save atomically and never send, touches require confirmed work or captured source_touch_id/request_id + occurred_at, lead/task retries dedupe via data.request_id while changed data conflicts, and the tool returns the record.

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 definition is front-loaded with the core create behavior and includes a 'When to use' section and an example. However, it is a dense wall of specialized clauses that partly duplicates the detailed schema, making it harder to scan 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 complex nested create tool, the description covers the main creation model, built-in versus custom behavior, sequence/touch edge cases, retry semantics, task due-date handling, and return behavior. With annotations and an output schema also present, an agent has enough context 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 coverage is 100%, so the baseline is 3, but the description adds useful semantics beyond the schema: custom owners default to the caller, display_field is usually name for propose_updates matching, task due_at should include the person’s UTC offset and due_has_time for stated times, and sequence/touch fields have special 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: create a built-in or custom record using object_type + data, with built-ins using typed domain logic. That distinguishes creation from update/delete, but it does not explicitly differentiate this tool from siblings such as log_touch, add_note, create_quote, or add_account_contact.

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 'When to use' section mostly restates the purpose: create built-in or custom records with object_type + data. It gives field-level guidance for sequences, touches, and task due dates, but does not say when to choose this tool over update_record, log_touch, add_note, or other create siblings.

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 annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false), the description discloses that the action re-enters the governance chokepoint and still respects approvals and write scope, and that the workspace automation flag is required for the rule to actually fire. It does not say what happens on duplicate label/rule key or subsequent invocations, which matters given the non-idempotent hint.

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?

Mechanics are front-loaded, followed by when-to-use, then an example — a clean triage order with no filler. Every sentence carries operational information (fire conditions, governance, flag prerequisite, edit path).

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-param, nested-object, mutation tool with an output schema and full annotations, the description covers prerequisites, governance behavior, and the edit alternative. The gap is failure modes (duplicate key, refused account-creating action at runtime) which are only partly covered by the schema's action_tool 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?

Schema coverage is 100%, so the baseline is 3, but the description adds the cross-parameter semantics: condition_spec gates on trigger facts, action_args is a {{placeholder}} template over those same facts, and the whole pipeline runs through governance. That linkage between action_tool and action_args isn't fully conveyed by the per-field schema text alone.

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 sentence states a concrete verb+resource (create an automation rule) and immediately explains the trigger/condition/action composition, which no sibling tool offers. It also explicitly distinguishes itself from update_record/delete_record for editing an existing rule, so an agent can separate it from the CRUD 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?

A dedicated 'When to use' line names the scenario (admin wants an action to fire automatically on a record write) and gives a concrete example. It also routes the editing case to the alternatives (update_record / delete_record on object_type 'automation') and points at describe_schema for the id/key.

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 idempotentHint=true; the description adds critical corrective context that nothing is deleted, that archived:true only removes a value from new picks while stored data stays valid and archived:false restores it, and that changes apply immediately. It also discloses the immutability constraint (an existing value_key's key and semantic role never change) and the atomicity rule for reordering, which annotations cannot express. It doesn't state permission mechanics beyond "admin-only" or failure modes for partial data, keeping it at 4.

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 operation set, then the patch/create rules, then archive semantics, then the reorder contract, and finally explicit when-to-use plus an example. Dense but every sentence carries a rule; only the return-value sentence is marginal given an output schema exists.

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 all four invocation shapes (create, patch, archive/restore, atomic reorder), the semantic_role gating for behavior-driving fields, reversibility, immediacy, and the absence of deletion. With 9 parameters and high-stakes mutation semantics, nothing an agent needs to call 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 3 is the floor, and the description genuinely adds cross-parameter semantics: patches apply only to supplied fields, a new key needs a label and (for behavior-driving fields) a semantic_role, and order must be sent alone with a complete value_key list including archived keys. This is coordinated-usage knowledge the schema does not convey on its own.

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 set of verbs (add, relabel, recolor, position, archive, reorder) against a specific resource (built-in pick-list values), and grounds the resource by pointing at describe_schema as the source of those values. This clearly separates it from define_field/define_object/define_pipeline siblings that define the containers rather than the values.

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?

"When to use: An admin changes a field's available pick-list choices" plus a concrete example gives an agent a clear trigger, and the description distinguishes the patch form from the order form. It stops short of explicitly excluding sibling alternatives like define_field (which creates the field itself), so it's strong but not fully routed.

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, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: conditional parameter requirements (relationship needs target_object, select/multiselect need options) and the fact that it returns the created field definition.

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 'When to use', then a concrete example. Every section earns its place, though the block structure is slightly longer than strictly needed for a well-covered schema.

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 a 5-parameter tool, an output schema present, and annotations covering safety, the description supplies the missing conditional logic and an example without needing to explain return values. An agent has everything required 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 already 100%, so the baseline is 3. The description goes beyond the schema by surfacing the cross-parameter conditionals in one place (field_type='relationship' → pass target_object) and enumerating the allowed type values, which helps an agent pick valid combinations.

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 ('Add a custom field') with scope qualifier ('any object that supports them — core objects with custom fields, or any custom object'). This cleanly distinguishes it from siblings like update_field, archive_field, and define_object.

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?

A dedicated 'When to use' line frames the trigger as 'an admin wants a new attribute on a core or custom object', which is clear operational context. It does not, however, explicitly contrast with update_field or say when not to add a field, so it stops 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?

Beyond the annotations (which only declare a non-read-only, non-destructive, non-idempotent write), the description discloses that the call is admin-only, that the anti-sprawl check can return matches INSTEAD of creating, and that display_field drives the entity matcher and cards. These are outcome-changing behaviors an 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 core action and the anti-sprawl behavior, then a when-to-use block and an example. Slightly penalized because anti-sprawl is stated twice (once inline, once in the when-to-use paragraph), which is 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?

An output schema exists, so return values need not be spelled out (the summary line 'Returns the created object definition' suffices). For a 7-parameter admin mutation, the description covers authorization, side-effect behavior, and the confirm escape hatch — everything needed 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 coverage is already 100%, so the baseline is 3. The description goes slightly further by explaining downstream semantics — that display_field feeds the entity matcher and cards, and that confirm_new is the mechanism to override anti-sprawl — adding meaning beyond the schema's field-level 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 new custom object TYPE') with concrete examples (Partner, Product, Investor) and explicitly ties it to how the type is then used (create_record / update_record / search_records). This cleanly separates it from siblings like update_object, define_field, and define_pipeline.

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?

Has a dedicated 'When to use' section stating the triggering condition (an admin tracking a kind of thing built-in objects don't cover), an exclusion (not a relationship type — investor/partner are stickers on a company or person), and the anti-sprawl escape hatch (confirm_new:true). 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 only establish the safety profile (writable, non-destructive, non-idempotent, closed-world). The description goes further: omitted stages seed from the workspace default, a type maps to exactly one pipeline, double claims and unknown type keys are rejected, and the call returns the created pipeline. It does not mention the uniqueness requirement being an error at runtime beyond the label's slug note, but the creation-side behavior is well disclosed.

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 operation, then seeding behavior, then a labeled "When to use" and "Example" section. Slightly over-long because the inline stage object shape duplicates the schema's own description, which is redundant rather than harmful.

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 the single "Returns the created pipeline" line suffices. For a 4-parameter create tool with rich annotations and a full schema, the definition covers purpose, seeding fallback, validation, and type mapping — only authentication/preconditions and alternative routing are absent.

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

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

Schema description coverage is 100%, so the schema already documents label, stages, applies_to and default_for_types in depth. The description largely restates what the schema says (stage shape, role enum, requires gate, type-to-pipeline mapping), adding little syntax or semantics the agent could not read in 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 and resource ("Create an additional pipeline") plus its scope (opportunities or a custom object), and the word "additional" plus "extra" cleanly separates it from update_pipeline/archive_pipeline in the sibling list. An agent can identify the operation 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?

An explicit "When to use" section names the trigger condition — a motion that needs its own stage sequence, with an investor-raise-vs-customer-pipeline example. It does not name the adjacent alternatives (update_pipeline, archive_pipeline) or state when NOT to create a new pipeline, so the routing guidance is clear but not exclusionary.

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 disclose mutation (readOnlyHint=false), non-destructive, non-idempotent, closed-world behavior. The description adds genuinely non-obvious context beyond that: the define-only lifecycle with no update/archive verb yet, and where edits must happen instead. It does not address duplicate-label behavior or key collisions beyond the schema's own note.

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 critical definition is front-loaded and the 'When to use' plus example are clearly separated. The opening sentence is long and dense with inline notation ({...}, applies_to), which slightly hurts scanability 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?

With an output schema present, the return value needn't be explained, and the annotations cover the safety profile. The description fills the remaining gaps on lifecycle, selection intent, and a worked example, leaving nothing an agent needs 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 baseline is 3, but the description adds conceptual meaning by explicitly relating the two key parameters: applies_to claims object keys while membership_spec decides which records land in the program. That division of responsibility is useful framing not obvious from the field list alone.

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 top-level program') and immediately frames what a program is (a parallel workstream peer to the built-in Revenue motion). This cleanly distinguishes it from structural siblings like define_pipeline, define_object, and define_field, which also create top-level entities.

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?

Contains an explicit 'When to use' clause naming the triggering scenario (an admin running a workstream alongside Revenue) plus a concrete example. It also pre-empts misuse by stating programs are define-only and that an admin edits them in Settings, so an agent won't hunt for an update/archive verb.

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=false, and the description adds real constraint context beyond that: the source must be a custom object, ARR/renewal fields are system-owned and cannot be targets, and it returns the created rollup. It does not explain why the operation is destructive or whether an existing rollup with the same key is overwritten, which is the one gap against the destructive 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 core definition and its constraints are front-loaded in the first three sentences, with the alternative-editing path and the example trailing as supporting detail. The 'When to use' line and the example restate ideas already introduced, so it is slightly longer than strictly necessary 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?

With an output schema present, the description needn't explain return values (though it notes 'Returns the created rollup'), and it covers the key domain constraints for an 8-parameter, 6-required tool. What remains unstated is the failure/conflict behavior implied by destructiveHint=true and idempotentHint=false.

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 key, agg, agg_field, filter_spec, source_link, source_object and target_object in detail; the baseline is therefore 3. The description reinforces the source/target restrictions (custom object only, ARR/renewal refused) but adds no syntax or format information the schema lacks.

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?

Uses a specific verb+resource ('Create a derived-metric rollup that aggregates a custom source object onto a target field') and immediately clarifies what that means with a concrete example (usage_revenue = sum of usage records). It also distinguishes itself from the generic create_record/update_record siblings by stating that editing an existing rollup goes through update_record/delete_record on object_type "rollup".

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 situation ('when an admin wants a computed field') and routes the agent away from this tool for the editing case, specifying the exact alternative path (update_record / delete_record on object_type "rollup", with id/key from describe_schema). The alternative and the condition that selects it are both stated, 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 only say destructiveHint=true; the description carries far more: a confirm-then-confirm:true flow, soft delete via deleted_at with no hard delete, quote-line cascade, restorable contact history/account links, and the blocking rule for accounts with open opportunities or subscriptions (with returned counts to guide remediation). It also enumerates exactly which object types remain as non-blocking history.

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 the DESTRUCTIVE warning, then the consequences, then alternatives, then an explicit 'When to use' plus example. The middle sentences are dense and clipped, but nearly every clause carries operational information an agent needs.

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, dependency-laden mutation it covers confirmation, reversibility, cascade behavior, blocking preconditions, and routing to alternatives. Return values are noted ('Returns the archived record') and an output schema exists, so nothing material is left for the agent to guess.

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 above that by giving confirm a procedural meaning (ask the user, then set true) rather than the schema's bare 'Boolean (true/false)'. object_type's refusal case for subscription and the admin-only keys are also reinforced, though most enumerations duplicate the schema.

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

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

Opens with a specific verb+resource+keying scheme: 'Archive by object_type + id,' immediately followed by the DESTRUCTIVE marker. It enumerates the supported object types and explicitly distinguishes itself from cancel_subscription and update_quote, so an agent can separate it from create_record/update_record/restore_record siblings 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?

'When to use: A mistaken or duplicate record should go (archive, soft delete)' states the triggering condition directly. It also names the exclusions and their alternatives: subscriptions use cancel_subscription or update_record, individual quote lines use update_quote. That is explicit when/when-not/alternative 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuinely new context beyond that – 'Every role can read; schema changes stay admin-only' and the fact that custom field/object/pipeline definitions carry the id consumed by update_record/delete_record. It says nothing about response size or pagination for what is clearly a large payload.

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 statement, then a labeled 'When to use' and a labeled example – a clean, scannable structure. The long comma-separated resource enumeration is dense but each item conveys real scope, so it earns its 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?

With an output schema present, the description needn't explain return values, and it already covers scope, read permissions, the discovery-before-write trigger, and id reuse across tools. The only omission is any hint about payload size or how to narrow what is described as a 'complete' workspace dump.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The only parameter-adjacent content is the note about ids accepted by update_record/delete_record with object_type, which is cross-tool context rather than input 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?

Names a specific verb (Read) and a richly enumerated resource set: objects, fields, valid values, FK graph, pipelines/stages, motions, qualification framework, programs, rollups, automation rules. That enumeration makes it unmistakable against siblings like get_context, show_workspace_setup, or get_pipeline_summary, which each cover only a slice.

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?

An explicit 'When to use: Discover the workspace's model and valid keys before reading or writing' gives a clear trigger condition. It does not name a competing alternative (e.g. get_context or get_help) or state when NOT to call it, 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?

Goes well past the annotations: discloses that exports traverse a single audited egress path and that each export writes a report_runs row plus an audit_log report.export event, and states the return payload (CSV text + row count + filename). It also discloses refusal behavior (dashboard or segment id rejected) rather than leaving it to error discovery.

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 operation and return shape, then parameters, then when-to-use. It is slightly repetitive: the 'When to use' paragraph restates 'one saved analysis or an inline ReportSpec as CSV' and the dashboard caveat already given in the opening paragraph, costing a little density.

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 and the description still names the returned fields; the precedence between report_id and definition, the dashboard exclusion, and the audit side-effect are all covered. For a two-parameter export 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 both parameters are already documented in the schema, including the report_id-wins precedence rule and the 'dashboard or segment id is refused' constraint. The description adds only a restatement ('Pass report_id for a saved analysis or an inline ReportSpec'), 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?

Opens with a precise verb+resource+format: 'Export one saved analysis's results as CSV,' and adds scope ('through the single audited egress path'). The dashboard caveat ('a dashboard is not one CSV') further sharpens what the tool does and does not cover, so it is distinguishable from report-reading/listing 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?

Has an explicit 'When to use' section plus a when-not condition (a dashboard needs a panel chosen first; it is not exported as one table). It stops short of naming alternative siblings such as run_report, show_report, or schedule_report, so the agent must infer the boundary from the schema's cross-reference instead.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds genuinely non-obvious behavior: omitted fields stay untouched, unknown feature keys are skipped-and-named (never a failure), while an unknown template_key is refused, and expected_active_motions acts as a concurrency guard returning updated:false. It stops short of explaining what gets destroyed or auth requirements, 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 core action, then behavior, then when-to-use and an example. Dense but each block earns its place; slightly long for a config-commit 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?

With 9 params, nested objects, an output schema (return values need not be explained), and annotations covering safety, the description supplies the key behavioral context an agent needs. Remaining gaps are minor edge cases rather than blockers.

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 3 is the baseline. The description exceeds it by disclosing ordering semantics (feature templates applied after motion templates) and the skip-vs-refuse distinction that the schema alone does not spell 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?

States a specific verb and resource — "Commit onboarding answers into the workspace config" — and immediately clarifies per-field behavior (active_motions, feature_templates, answers). This lets an agent distinguish it from siblings like update_workspace or show_workspace_setup 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?

"When to use: Call at the end of the interview once the user has confirmed the choices" gives an explicit trigger condition. It does not name alternative siblings (e.g. update_workspace for later edits), so routing is clear but not fully contrastive.

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 readOnly/openWorld/non-idempotent; the description supplies the behavior that matters: nothing is held yet, holds happen later in propose_meeting, dropped_co_hosts must be relayed, and starts_at/ends_at are opaque so no reformatting or timezone math. It also specifies output presentation (card vs. rationale bullets) even though an output schema exists.

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 key constraint (nothing held, quote rationale verbatim) and every sentence carries an operational rule. It is telegraphic and dense — semicolon-chained clauses plus a guide pointer — which costs some readability, but there is little 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 10-parameter tool with modes, output schema, and destructive downstream steps, it covers state, sequencing, and the main failure path (real conflict → search again; overrides/shortfalls deferred to a guide). The deferral of override and shortfall handling to capable://guide/scheduling leaves a small gap, but 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 baseline is 3; the description still adds mode-level semantics not obvious from the schema — current_slots alone commits, current_slots+propose_label re-picks and awaits a yes, and co_host_emails excludes invitees in favor of invitee_timezone. Most remaining per-parameter detail (hour bounds, target_starts_at failure behavior) is already in the schema, so it does not reach the top band.

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 with scope: "Find three chronologically labeled slots; nothing is held yet." The contrast with propose_meeting ("propose_meeting rechecks availability before placing holds") makes the boundary unambiguous, which matters given many scheduling 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?

Explicit routing rules: use this for candidate times, call propose_meeting once times are chosen, and "never call find_times again to validate, swap, commit or re-render them; search again only if the user asks for different times or a real conflict is returned." It also defines the three invocation modes (FRESH / SWAP / COMMIT) and when each applies.

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 readOnlyHint=true, the description discloses that it never activates, that a null value means an existing pricing contract, that 'quiet' means active accounts idle 90+ days with nothing open, and that archiving is done by a person at review_url (human-in-the-loop). These are substantive behavioral facts 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?

Purpose is front-loaded and the description is split into purpose, when-to-use, and example. The first paragraph is a bit telegraphic ('approval need, live work blocking archive') and relies heavily on inline backtick terms, 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?

An output schema exists, so return-format detail is unnecessary. The description covers the non-obvious behavior for a single-param read tool: state semantics, the omit path, the quiet/human-review flow, and the read-only guarantee. 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% for the single optional account_id, so baseline is 3. The description earns above baseline by expanding what omitting the parameter does ('quiet' = active accounts idle 90+ days, nothing open, person acts at review_url), adding meaning beyond the schema's terse 'Omit for quiet accounts'.

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 (a company's billing state) and enumerates the states (prospect, working=paid active, archived) plus the fields returned. 'Never activates' cleanly separates it from the sibling manage_company_billing mutation tool, so an agent can distinguish read vs write 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?

The 'When to use' block explicitly states the trigger ('before activating or archiving') and covers the no-account_id mode, with a concrete example. It doesn't explicitly name manage_company_billing as the write alternative, but the read/write split is strongly implied by 'Never activates'.

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 establish readOnly/openWorld behavior, and the description adds crucial context: per-section coverage states, failed sections not implying absence, LinkedIn exact verified identity, conflicts stopping linking, conversations listed without message text, and no sharing/syncing. This is substantial behavioral detail beyond 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?

The description is dense but structured, with semicolon-rich mode summaries and a clear example; most clauses carry useful behavioral detail. However, the 'When to use' guidance is placed after long mode descriptions rather than front-loaded.

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 8-parameter, multi-mode read tool with an output schema and rich annotations, the description covers purpose, modes, coverage caveats, identity constraints, privacy, and usage. Nothing critical 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% and the parameter descriptions are already highly detailed, including linkedin_thread_id parsing and match_linkedin_email behavior. The tool description mainly restates high-level modes and adds little parameter-level semantics beyond the schema, 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?

The description names the resource and return shape: 'Bounded record context with per-section coverage' and enumerates account context and other type+id reads. It covers multiple modes but never contrasts with sibling get_record, so an agent could still wonder when to use get_record instead.

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 includes a dedicated 'When to use' line: broad record questions, before multiple searches, and says to use account_id or type+id. That gives clear context but no when-not guidance or explicit alternatives such as get_record/search_records.

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, non-destructive), yet the description adds substantial behavior the annotations do not: verbatim search with citations required, the confident:false failure path, the hello@capable.run fallback, and the caveat that diagnostics report setup facts rather than live provider health. It also discloses the unknown-key fallback behavior. This is rich behavioral context beyond 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?

Purpose and the primary alternative routing are front-loaded in the first two sentences, and the example anchors intent well. The middle section is dense, packing citation rules, failure protocol, and diagnostics caveats into long compound sentences, so it reads as somewhat cluttered rather than crisply 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?

For a zero-required-parameter help tool with an output schema available, this covers everything an agent needs: what it searches, when to call it, how to handle low confidence, what diagnostics does and does not prove, and which sibling to prefer for CRM questions. Return shape is delegated appropriately to the output 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 the baseline is 3, but the description adds real semantics: article_key fetch vs. verbatim search, the interaction with diagnostics ('before saying their mail or calendar isn't connected'), and the scoping of diagnostics to saved settings only. It stops short of restating parameter formats, which is fine since the schema handles 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?

Opens with a specific verb+resource pair: 'Search verified Capable how-to/setup/troubleshooting articles verbatim with citations, or fetch article_key.' It explicitly names the sibling alternatives (get_context/search_records) as being for CRM data, so the boundary is unambiguous 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 an explicit 'When to use' clause ('Questions about Capable itself works, or checking saved connection status'), an exclusion routing rule to get_context/search_records for CRM data, and a conditional trigger for diagnostics ('before saying their mail or calendar isn't connected'). When-to-use, when-not-to-use, and alternatives are all 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?

Annotations already declare read-only/non-destructive, but the description adds materially new behavior: pipeline scoping applies only to opportunity breakdowns while revenue/renewals/at-risk stay workspace-wide, renewals cover a 90-day window where totals include every renewal but the list caps at 500 with coverage/truncated flags identifying a sample. It also preempts a likely misread with "Nothing predicts" and details forecast composition (per-person rows, tree rollups, separate currencies, targets, human calls, supporting deal IDs).

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, scoping rules, metric semantics, when-to-use and an example are laid out in a front-loaded order with little filler. It is dense and slightly run-on, and the one-line example adds marginal value, but each sentence carries a distinct 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?

Given an output schema exists, the description need not enumerate return fields, yet it covers exactly the non-obvious behaviors an agent would otherwise get wrong: scoping asymmetry, the 90-day renewal window, the 500-item list cap with truncation signaling, and forecast row composition. 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 coverage is 100%, so the schema baseline already documents all three parameters. The description still adds meaning beyond it by clarifying that pipeline_key/pipeline_id scope only the opportunity breakdowns, that omitting both yields the default pipeline plus unassigned deals, and that other metrics remain workspace-wide.

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 sentence names a specific verb+resource and even the mechanism ("Summarize opportunities by type/stage and pipeline_by_lens using stage roles, not labels"), and it lists the concrete payload (revenue, renewals, forecast). It does not explicitly name the sibling it competes with (e.g., run_report or show_report), so an agent must infer the boundary from the "not vague data exploration" caveat.

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 explicit "When to use" line gives both inclusion criteria (sales workspace with opportunities, forecast/renewals/ARR questions) and exclusions ("not vague data exploration or before motion setup"). It stops short of naming the alternative tool to pick when the conditions fail, which keeps it below 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 non-obvious behavior: a wrong or omitted `type` self-corrects, and a stale/unknown/malformed id returns {found:false} with a recovery search rather than an error. It also flags that governance records are admin-only, which is auth context 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?

The critical behavior (id is authoritative, type is optional) is front-loaded in the first two sentences, and the when-to-use/example tail is short. The long enumeration of built-in object types is the one part that could be trimmed without loss.

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 need not document return shape, and it instead covers the one return case that matters (not-found). For a simple 3-param read tool, an agent has everything needed to invoke it correctly and interpret failures.

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 goes beyond the schema by explaining that `type` is a mere hint whose inaccuracy is harmless, which changes how an agent should populate it. `include_archived` is left to the schema's bare 'Boolean (true/false)' note, which keeps 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 and resource ('Fetch any record's full detail by id') and enumerates exactly which object families are covered, including custom keys and admin-only governance records. It also positions itself relative to siblings ('less common than search_* tools', 'list them with search_records'), so an agent can distinguish 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?

A dedicated 'When to use' section plus the example 'Fetch opportunity <id>' gives clear context, and it names the competing approach (searching) explicitly. It stops short of stating when not to use it (e.g. bulk retrieval, or when only a summary is needed), so it lands at 4 rather than 5.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it defines the meaning of each resulting state (Submitted returns the frozen selection, Pending awaits approval, superseded requires the latest review, expired proves no first commit) and gives retry/polling semantics, which the annotations do not 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-loaded with the core action and the non-approval constraint, then organized into state meanings, a when-to-use line, and an example. It is dense and largely earns its space, though the phrasing across state meanings is terse enough to border on cryptic and the example sentence is marginal.

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 shapes need not be explained, and the description nonetheless pre-explains the meaning of each status value plus retry guidance and a fallback when execution is uncertain. For a single-parameter read tool with full annotation coverage, 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 description coverage is 100% and there is a single parameter whose 'unchanged receipt' semantics are already documented in the schema. The description reinforces that the receipt must be unchanged and ties it back to review_proposed_updates, but 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?

States a specific verb and resource ('Read a review's shared status') and immediately scopes it against siblings by saying 'without approving or executing changes', which contrasts with commit_reviewed_updates and review_proposed_updates. An agent can distinguish it from the other review tools 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?

The 'When to use' line gives an explicit trigger ('Synchronize a review after chat approval or correction, using its unchanged receipt'), and it adds a concrete alternative behavior ('inspect CRM state before another save') plus polling discipline ('Poll with backoff only while viewing a pending or executing review'). It stops short of naming the specific sibling tool to use instead for the fallback inspection, so it is clear but not fully 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 the readOnly/destructive/idempotent profile, yet the description adds non-obvious behavior: pages are workspace-scoped while availability and calendar choices apply across workspaces, draft URLs cannot accept bookings, and updated_at versions are returned for edits. It also supplies a guardrail ('never invent a page ID, calendar ID or URL'), which is genuinely useful call-site context beyond the 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-loads what is read, then cleanly separates 'When to use' and 'Example'. The workspace-scope sentence is dense but earns its place; overall slightly long but well-structured and waste-free.

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. Combined with scoping rules, when-to-use triggers, guardrails, and a guide reference, an agent has everything needed to select and 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?

No input parameters exist, so the baseline is 4. The mention of page IDs, calendar IDs, and URLs refers to data the tool surfaces for other tools rather than its own inputs, so it does not add parameter semantics here, but nothing is missing.

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 enumerates the exact resources: booking pages with shareable URLs, saved availability, and the calendar connection (status, provider, calendars). This is clearly distinguishable from siblings like save_booking_page, update_availability, and update_scheduling_calendars.

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 'When to use' section gives explicit triggers — user questions about booking links/hours/calendars, and before changing scheduling settings or declaring a calendar disconnected. It provides clear context but does not name the specific sibling tools (e.g., update_scheduling_calendars) it precedes, leaving the alternative unmapped by name.

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 annotations, the description explains duplicate suppression via external_id, retry requirements for new work, source_touch_id reuse behavior, sequence_action outcome semantics, and the reserved custom_fields key. These details materially affect how the agent should call the tool and avoid duplicate activity.

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 and is appropriately sized for a 16-parameter nested tool, including a concise example. Some instructions are packed into dense semicolon chains, which slightly reduces 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?

Given the complex schema, nested objects, annotations, and existing output schema, the description covers the key usage paths, duplicate/retry behavior, and sibling routing needed to invoke the tool correctly. Nothing essential appears 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 all parameters are already documented structurally. The description adds useful semantics for critical parameters such as external_id, source_touch_id, request_id/occurred_at retries, and sequence_action, though it does not explain every 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?

The description states a specific verb and resource: record a call, email, meeting, or LinkedIn activity, with account/contact/opportunity linkage. It distinguishes clearly from propose_updates and commit_reviewed_updates in context, but does not explicitly differentiate itself from the sibling record_meeting tool.

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 ('After any meaningful interaction'), tells the agent to check existing activity before logging, and names alternatives/paths for captured meetings, approved reviews, synced external activity, and duplicate suppression. The conditions for using source_touch_id versus request_id are also 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?

Adds substantial context beyond annotations: approve actually executes the captured call as the original requester, outcomes can be applied/failed/expired/uncertain, deny closes without executing, confirm:true is required after previewing, requesters cannot decide their own requests, and a require_approval policy on this tool blocks it while queue operations never queue themselves. These are exactly the safety facts the destructiveHint/readOnlyHint flags cannot convey, and nothing contradicts those 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?

One dense paragraph, but it is front-loaded (purpose first, then per-action semantics, then constraints, then when-to-use and example). Sentences earn their place, though the mid-paragraph shift into approve/deny mechanics could be split for faster scanning.

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

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

Covers a multi-action, destructive, execution-triggering tool end to end: allowed actions, decision prerequisites, execution side effects and their uncertain states, authorization limits, and self-recursion behavior. With an output schema and annotations already present, 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 coverage is 100%, so the baseline is 3; the description still adds decision-relevant meaning by explaining the two-phase confirm flow ('requires confirm:true after previewing tool, target, requester and age') and that an uncertain outcome requires inspecting the affected record first. Defaults for days/limit are left to the schema, which is fine.

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 the resource and scope precisely: an admin-only governance queue for requests held by policy/autonomy. Each action is then defined by what it does (list returns captured tool/args..., approve records a decision and runs the captured call, deny closes without running), which no sibling tool offers. An agent can distinguish this from review_proposed_updates, get_review_status, or update_workspace 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?

Explicit 'When to use: An admin reviews held requests or evidence before changing autonomy' plus a concrete example question routes the agent correctly, and it names update_workspace.autonomy_by_role as the place to configure rather than manage. It stops short of stating negative cases (e.g. non-admin callers, or queueing a request instead of deciding one), so it is strong but not complete.

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 destructive/idempotent/openWorld/non-readOnly, but the description goes well beyond them: it discloses the administrator-granted automation budget requirement, that the fallback is a pending human approval rather than an activation or capacity purchase, that live-price/revision drift causes refusal, and that archive/restore can only happen in the web panel.

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 and constraints are front-loaded, and the sentences carry real information. It loses a point for mild redundancy, since the archive/restore web-panel constraint is stated in the opening paragraph, repeated in 'When to use', and echoed by the example.

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 explained, and the description covers everything else an agent needs: the quote prerequisite, the exact-value requirement, the automation-budget precondition, the approval fallback, and the actions this tool cannot perform.

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 operational meaning on top: it tells the agent to never guess the revision and price, to supply them in the billing currency's minor units (cents or öre), and to reuse the idempotency key on retries. This reinforces the most failure-prone inputs rather than merely restating 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 verb set (activate or request human approval for activation) and resource (company billing state), and names the sibling it depends on (get_company_billing). It also explicitly carves out what the tool cannot do (archive/restore), so an agent can distinguish it from neighbors 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?

Includes an explicit 'When to use' line, names the prerequisite read tool, states the alternative path for archive/restore, and gives clear exclusions ('Never invoke this merely to read, enrich, import or qualify a company'). Nothing about routing 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?

The description goes well beyond the annotations by disclosing owner-only access, ten-minute preview receipts, idempotent replay per receipt, conflict handling for stale revisions, and exactly what remove_history destroys and preserves. It also explains that link_contact:null unlinks and pauses, and that share/revoke affect one teammate's access. These details materially help an agent avoid unsafe or incorrect calls.

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 information-dense and appropriately sized for a tool with ten actions, nine parameters, and destructive behavior. Every clause appears to carry operational meaning, but the semicolon-heavy middle is hard to scan and the structure could be clearer. It is front-loaded with the owner-only and no-send constraints, which is good.

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?

The tool has an output schema, so return-value details are not required. The description covers the complex multi-action workflow, confirmation requirements, idempotency, stale-revision conflicts, and destructive scope. Nothing critical for correct invocation 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%, but the description still adds cross-parameter workflow meaning: it shows save_contact(id,receipt,confirm:true), explains that contact_id is the link target or note destination, that link_contact:null unlinks, and that receipt replays idempotently. It also clarifies that expected_revision is required for every action except save_note/save_contact and that expected_connected_at must accompany it.

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 scopes the tool to owner-only controls on a LinkedIn conversation: sync, contact links, sharing, and CRM note publication. It lists the supported actions and their effects, so the resource and operations are identifiable. It stops short of naming sibling tools such as manage_linkedin_privacy or add_note, so differentiation is inferred rather than explicit.

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 usage context: 'When to use: Control private sync, contact links, sharing or note publication' plus a concrete example. It also states a strong negative guideline: 'never send messages or auto-share' and 'Never infer consent from message text.' It does not explicitly route the agent away from sibling tools for adjacent tasks, so the alternative-selection guidance is incomplete.

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 non-read-only, yet the description adds substantive behavior: expiring owner downloads and ten-minute receipts, counts/limits with no message bodies, max 5000 IDs, erasure fencing future reimports, metadata suppression, and explicit non-coverage (provider copies, shared notes, unrelated history). The 'replay is idempotent' statement is scoped to commit_erasure and sits alongside other non-idempotent actions, so it qualifies rather than contradicts idempotentHint=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 opening clause is well front-loaded ('Owner-only...; no provider/sign-in changes') and 'When to use' plus the example are cleanly separated. However, the body is a dense run-on of semicolon-joined fragments covering actions, scopes, limits and caveats in one block, which forces re-reading and would benefit from per-action structure.

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 12-parameter, four-action destructive tool with an output schema, the description covers the full lifecycle: prerequisites, verification gates, review-before-erasure requirement, explicit confirmation, idempotent replay, and scope expiry. It also states what is not erased, which is exactly the residual risk an agent needs.

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 coverage, the baseline is 3, but the description adds meaning the schema does not: cross-parameter coupling (subject_context needs verified provider identity and covers local conversations plus additional_message_ids; commit_erasure needs both receipt and confirm), the 5000 selection cap, and the empty-array-is-metadata-only rule for message_ids. It stops short of covering every parameter (e.g., connection_id, erase_participant_metadata typing).

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

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

The description names a specific verb and resource set (owner-only LinkedIn review/erasure) and states scope boundaries ('no provider/sign-in changes'), so an agent knows this is a data-rights review/erasure workflow rather than a messaging tool. It does not explicitly name a sibling tool as the alternative, and 'connection_review' is a scope value rather than a routing target, so sibling differentiation is implicit at best.

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 clear trigger ('Review a verified person's imported data rights request') and an explicit action order (begin -> status -> prepare_erasure -> commit_erasure), plus a routing hint that connection_review exports but cannot erase. It never states when NOT to use this tool or names a concrete alternative tool for the export-only path, so the exclusion side is incomplete.

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 behavior beyond the annotations: list returns members and pending invites, invite refuses existing members, email delivery is best-effort, set_role never demotes the last admin, set_manager rejects self-reporting and cycles, set_read_scope cannot restrict admins, remove cannot target self or last admin, and destructive actions preview until confirm:true. These are meaningful mutation and constraint details for a destructive tool.

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

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

The description is dense but appropriately sized for a nine-parameter, multi-action administrative tool, and it front-loads the admin-only scope before enumerating action behavior. The semicolon-heavy action list is efficient but slightly reduces scanability, so it is strong rather than perfect.

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, destructive annotations, 100% schema coverage, and output schema, the description covers the essential admin restrictions, action semantics, confirmation preview behavior, and workspace-bound limitation. An agent has enough context to select and invoke the correct action without needing return-value details in the 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?

Schema coverage is 100%, so the schema already defines all parameters; the description still adds action-level semantics such as invite defaulting to member, manager_id null clearing a reporting line, read_scope null following role defaults, and confirm returning a preview unless true. This is useful cross-parameter guidance, though much of it is also present in the 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?

The description states a specific resource and verb set: admin-only membership controls, with each action named (list, invite, revoke, set_role, set_manager, set_read_scope, remove). It clearly distinguishes this as membership/invitation/access management rather than generic record or billing management.

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

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

It gives clear usage context: "When to use: An admin manages membership, invitations or an individual's access," plus an example invite. It does not explicitly compare alternatives or exclusions, but the admin-only scope and action list make the intended context 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?

Adds substantial context beyond annotations: remove is two-phase ('first call asks, then requires confirm:true' deletes nothing), only Capable-created blocks can be modified, create is capped at 24h, list caps at 62 days, and request_id reuse is limited to retrying the same block (consistent with idempotentHint=true). It does not describe the confirmation-prompt return shape or failure modes when editing a non-Capable block, so it falls short of the top score.

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 a compact per-action block of constraints, then 'When to use' and an example. Nearly every clause carries operational information, though the action paragraph is a dense run-on that could be split for faster scanning.

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

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

For a 13-parameter, four-action tool with an output schema and annotations already present, the description covers the prerequisites (Capable-created blocks, confirm flow, request_id freshness, duration/range limits) an agent needs to call it correctly. Remaining gaps — per-action return contents and the confirmation-prompt payload — are partly covered by the output 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 the baseline is 3, but the description adds cross-field semantics the schema lacks: create requires title/starts_at/ends_at with a max 24h span, request_id must be fresh and reused only for retries, update with starts_at alone preserves duration, and show_as defaults to busy gating booking pages and find_times. Minor params (time_zone, notes) 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 concrete verb set (manage/create/update/list/remove) over a specific resource — personal Google/Outlook calendar blocks with no attendees — and immediately bounds the scope: 'nothing is sent.' It also names the sibling it is not (find_times for meetings with others), so the agent can distinguish 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?

The 'When to use' line gives positive triggers (block focus time, add reminders, adjust your own blocks) and an explicit alternative plus its condition ('use find_times for meetings with others'). A worked example ('Block 9–11 tomorrow for writing') further anchors 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 annotations, the description discloses admin-only access, signed JSON payload contents, oldest-first delivery after a minute, preview-and-confirm behavior for sensitive actions, retry/backoff behavior with disabling after a day, and the 10-per-workspace and HTTPS public-host constraints. These are concrete behavioral traits an agent needs before invoking destructive or open-world actions.

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 and front-loads the action summary before usage guidance and an example. It is appropriately sized for a multi-action administrative tool, though the sentence packing is heavy and the example adds limited value.

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 complex action-based interface, full schema descriptions, annotations, and an output schema, the description covers the operational context, constraints, confirmation flow, and failure behavior needed to invoke the tool correctly. No critical invocation detail 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 description coverage is 100%, so the schema already documents every parameter thoroughly. The description reinforces key semantics such as confirm:true preview behavior and object_types null meaning all objects, but much of that is already present in the schema, so it does not substantially exceed the baseline.

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 operation set: admin-only change-feed webhooks, with each action named (list, create, update, pause/resume, rotate_secret, test, delete). It also explains what the tool is for in business terms: letting an admin connect another system to CRM changes without polling.

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 clear usage context in the 'When to use' line and an example, which is enough to select the tool for webhook administration. It does not explicitly compare against alternatives such as read_changes or polling, 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 destructiveHint=true and non-idempotent, but the description adds substantial context beyond them: blank fields fill without overwriting, links move, identities stay with the survivor, the archived duplicate redirects by id, colliding rows are retained in duplicate history and reported in collisions, account merges require workspace admin and active Core workspace, and Core billing rules apply. This is exactly the behavioral detail an agent needs for a destructive merge.

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: core merge behavior appears first, followed by a clear 'When to use' section and an example. Every sentence carries relevant operational detail for a destructive tool with eight parameters. It could be slightly tightened, but the length is justified by the complexity.

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 destructive nature, eight parameters, 100% schema coverage, and an output schema, the description covers everything an agent needs: listing vs merging modes, preview/confirm semantics, collision handling, identity retention, prerequisite conditions for account merges, and the archived-duplicate redirect. No critical gaps remain.

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 beyond the schema by explaining the default listing behavior when keep_id/merge_id are absent ('list possible duplicates with the older record proposed to keep') and how record_id narrows that list. It also clarifies that only confirm:true performs the merge. The schema already documents most parameter semantics, but the description supplements them usefully.

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: 'Merge duplicate contacts/accounts.' It explicitly distinguishes merging from deleting ('merge to preserve history instead of deleting the twin') and clarifies the two supported object types. An agent can tell this apart from siblings like delete_record or update_record 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 provides an explicit 'When to use' section: 'Two records represent one person/company: merge to preserve history instead of deleting the twin.' It also states the alternative (deleting the twin) and describes the listing mode when keep_id/merge_id are omitted. The 'Preview first; only confirm:true changes data' guidance further clarifies safe 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 only give readOnlyHint=false and destructiveHint=false; the description goes well beyond them: preview performs no writes, stage stores the identical preparation, identical source identity/payload is skipped, changed identities and email/domain collisions require manual resolution and 'never name merges', approvals block imports, historical imports emit no automation events or enrichment, and waiting rows persist for resume. It also discloses that start retries unsuccessful rows after execution without duplicating an already-imported source identity.

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 and nearly every clause carries real information (dedupe, collisions, approvals, unsupported objects, aliases), so it is not padded. However, distinct concerns are flattened into two long semicolon-chained paragraphs, making the workflow order and the caveats hard to scan; bullets or phase labels would have made it far more usable.

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-action, 13-parameter bulk-mutation tool, the description covers the full lifecycle, safety posture, dedupe/collision policy, prerequisites, resumability, and what is out of scope. Limits, retries and authority are correctly delegated to the schema, and an output schema exists so return-value explanation is unnecessary.

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 per-action authority, row paging and mapping rules are already fully documented in the schema, so the baseline 3 applies. The description adds only a pointer ('See inputs for authority, mappings, limits and retries') and the fact that snake_case aliases are accepted, which is genuinely useful but thin given 13 parameters and two enums.

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 'Admin CRM import' plus the explicit action pipeline (describe → preview → stage → start), and the example 'move our CRM data to Capable' makes the verb+resource concrete. It never states plainly that records get created in the destination CRM, and no sibling is named for contrast (e.g. create_record for single records), but no sibling could be confused with a bulk import, so differentiation is implicit.

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?

'When to use: An administrator imports a Salesforce, HubSpot, Attio or CSV export with explicit mappings and resumable progress' gives a clear triggering condition and actor. It also supplies ordering rules (resolve approvals first, preview before stage, explain activationGuidance before start) and exclusions ('Custom objects, workflows, attachments and unavailable history need separate scoping'). It stops short of naming what to use instead for those excluded cases.

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 annotations, the description discloses that holds are reversible, expiring, invitee-invisible, and never emailed; that the email is staged; that dropped co-hosts must be relayed; and that busy overrides behave differently from race-dropped busy slots. It also explains the authorization model: a clear human go on content authorizes sending via send_meeting_invite in the same turn. These are material behavioral traits not carried by 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 description is dense but front-loaded, stating the core behavior first and then workflow constraints, parameter pitfalls, return values, authorization, and a use-case note. Every sentence carries operational value for a 16-parameter scheduling tool. There is little or 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?

Given the complexity, 16 parameters, and an output schema, the description covers the essential workflow, prerequisites, authorization boundary, co-host constraints, ID validation, and returned artifacts such as picker_url and staged_invite_preview. An agent has enough context to call this correctly and to know when to route to send_meeting_invite.

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 operational meaning by requiring exactly three find_times slots verbatim, restricting co_host_emails to workspace members, directing invitees to invitee_email or additional_invitee_emails, and requiring search for known IDs rather than invention. It also explains why busy_override_starts exists and when to list a start. Some of this repeats schema descriptions, so it is strong but not fully additive.

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 places reversible, expiring, invitee-invisible calendar holds and stages an invitee email without sending it. It explicitly distinguishes this from send_meeting_invite and from find_times by describing the exact stage-and-defer behavior. An agent can identify precisely 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 explicit timing: use after the user chooses times and approves the content, and first confirm topic and agenda once. It also names the follow-on alternative send_meeting_invite and the condition for calling it in the same turn, plus the exception for withholding when told to hold or when invitee_email is absent. This is unusually complete routing guidance.

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