Capable

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

Annotations declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered; the description adds genuinely new behavioral context by disclosing that setting is_primary_champion auto-clears any previous primary (at most one per account). That is exactly the kind of side effect an agent must know before calling. It does not discuss permission requirements or response shape, but those are lower value here.

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

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

Three short blocks (core semantics, when-to-use, example) with the most decision-relevant facts front-loaded. Slight redundancy in restating the role default list that also appears in the schema, but no filler sentences.

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

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

For a 5-parameter mutation tool with full schema coverage, an output schema, and annotations, the description supplies everything else an agent needs: when to invoke, id-resolution prereq, exclusivity side effect, and the sibling distinction. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds real meaning beyond the schema by enumerating the seed role values and explaining the exclusivity semantics of is_primary_champion. It stops short of describing notes handling in prose, which the schema already covers.

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

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

States a specific verb and resource ('Link a contact to an account') and immediately differentiates from the sibling concept opportunity_contacts by explaining that account_contacts persist across the customer relationship. An agent can select it confidently 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' section plus a worked example ('Add Sarah Chen as the primary champion at Acme'), and a prerequisite telling the agent to resolve ids via search_* first rather than inventing them. It also names the near-sibling remove_account_contact implicitly through the inverse framing, and contrasts with opportunity_contacts.

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

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

With annotations already declaring readOnly=false, destructive=false, the description adds genuinely new behavior: notes are searchable and soft-deleted (i.e. recoverable), and it returns the created note. It does not discuss the required link cardinality's effect on failure modes, but the added context is solid.

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

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

Three short, front-loaded blocks: what it does, when to use it, and a worked example. No sentence is redundant, and the hard constraint ('MUST link to at least one') appears early where it will be read.

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

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

An output schema exists, so return values need not be spelled out, and the schema fully documents every parameter including the request_id retry semantics. What remains — when to use, the linking constraint, and note lifecycle (searchable, soft-deleted) — is all present.

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 adds a constraint the schema does not express — that at least one of account_id/contact_id/opportunity_id/touch_id must be supplied — which is exactly the kind of semantic an agent would otherwise miss (the schema only requires 'body').

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 ('Attach a free-form note to any record'), enumerates the record types it can attach to, and states the return value. This distinguishes it clearly from create_record or log_touch, which write structured data rather than free-form context.

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 an explicit selection criterion, reinforced by a concrete example. It does not name a specific sibling as the alternative for structured data (e.g. update_record), 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 the operation writes (readOnlyHint=false, destructiveHint=false) and is idempotent (idempotentHint=true). The description usefully extends this with 'Admin-only,' the skip-existing behavior ('never duplicates'), and the unknown-key fallback returning available templates with a did-you-mean suggestion rather than an error. However, it also explains return contents even though a full output schema exists, so much of the added prose overlaps structured data rather than contributing new behavioral context.

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

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

Front-loaded with the core action and impact, then when-to-use and an example. It is somewhat long and repeats the idempotency point twice ('keys that already exist are skipped' and 're-applying only adds what's missing'), and the explicit return-value sentence is redundant given the output 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?

Given a single required parameter, full schema coverage, and an output schema, the definition covers everything needed: admin-only prerequisite, idempotency semantics, error/fallback behavior for bad keys, a pointer to describe_schema for discovering keys, and a usage example. Return values are correctly left 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 description coverage is 100% and the schema already states the key must be one of describe_schema's `templates` keys with an example. The description largely restates this (pass the template's key), adding only the unknown-key fallback behavior. Baseline 3 is appropriate when the schema already carries the parameter documentation.

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 expands the resource concretely as a pre-vetted bundle of objects, fields, pick-list values, pipelines, and starter views. It distinguishes itself from the manual-construction siblings (define_object, define_field, define_pipeline) by framing the action as adopting a whole bundle 'instead of defining each piece by hand.'

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' section names the condition (an admin adopting a whole curated bundle at once) and the alternative approach (defining each piece by hand), plus the prerequisite 'Admin-only.' An agent can route to this tool over the define_* siblings without inferring anything.

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

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

Goes well beyond the destructiveHint annotation: discloses the mandatory two-step preview/confirm flow, that stored values are NOT deleted but become unread orphans that reappear if the key is redefined, that built-in fields can't be removed, and that an unknown key returns the object's custom field keys. This is exactly the non-obvious behavior an agent needs.

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 the DESTRUCTIVE warning, then details consequences — good ordering. The "When to use" paragraph largely restates the first paragraph (preview then confirm, orphans returning), so a small amount of text 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?

For a destructive mutation with an output schema already covering the return value, the description supplies the destructive semantics, the two-step safety flow, the permission boundary, and the orphan-value behavior. 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% and the schema already documents key (not label), object_type, and the confirm preview semantics. The description reinforces the confirm flow but adds no syntax or format detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb and resource — "Remove a custom field's DEFINITION by object_type + key" — with the scope qualifier that only the definition (not values) is removed. This clearly distinguishes it from siblings like define_field, update_field, and archive_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?

Provides an explicit "When to use" (an admin retiring an unused custom field) plus the operational condition that it applies only to admin-defined fields, not built-ins. It stops short of naming sibling alternatives (e.g. update_field for renaming) or explicit when-not-to-use guidance, so it lands just below the top.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description usefully adds what actually happens (records retained, object removed from registry), the built-in refusal constraint, and the return value, though it omits permission requirements and whether the archive can be reversed.

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 scoping behavior is front-loaded, which is good, but the key fact "Existing records are kept but the object disappears from the registry" is stated twice (in the opening sentence and again under "When to use"), costing space without adding information.

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

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

An output schema exists so return values need not be explained, and the description covers the retention semantics and built-in restriction. For a single-parameter mutation it is nearly complete, with only reversibility/permission details left unstated.

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

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

Schema description coverage is 100% with a single well-documented 'key' parameter, so the schema already carries the parameter meaning. The description's 'by key' and 'built-in keys are refused' merely restate what the schema documents, 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 (soft-delete/archive) and resource (custom object type), scoped by key, and clearly distinguishes itself from sibling archive tools like archive_field and archive_pipeline. An agent can identify the target of 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?

Explicitly says when to use it ("When an admin no longer needs a custom object") and gives a concrete example. It doesn't name alternatives such as update_object or a restore path, so routing guidance is present 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?

Annotations already declare destructive/safe-write/idempotent, but the description adds substantial context beyond them: soft-delete recoverability by an admin, the live-opportunity refusal, the undefeatable default pipeline, the benign unknown-key behavior (returns known pipelines rather than erroring), admin-only auth requirement, and the return value.

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 the key precedence, then prerequisites, in a logical order. It loses a point for restating the reassignment constraint twice (main body and 'When to use'), which is redundant given how compact the rest is.

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 carrying the safety profile and an output schema covering the return value, the description still supplies everything else an agent needs: auth requirement, prerequisites, edge-case behavior, and recoverability. Nothing material is missing.

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

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

Schema description coverage is 100%, and the schema descriptions already state 'id wins if both are given' and 'Prefer this.' The description reinforces the key/id precedence but adds no format or syntax detail beyond what the schema provides, 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?

States a specific verb and resource ('Archive (soft-delete) a named pipeline') and precisely names the two identifier parameters. It is clearly distinguishable from sibling archive/delete tools (archive_field, archive_object, delete_record) and from update_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?

The 'When to use' section states the condition ('an admin no longer needs a named pipeline') and the blocking precondition ('Refused while deals are still on it — reassign those first'). When-not guidance is explicit, not implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it discloses that the first call is a no-op preview returning {cancelled:false, requires_confirm:true}, that every host's tentative holds and any confirmed event are released, that a booked invitee receives a cancellation email, and that the action is irreversible. That is exactly the behavioral context a destructive tool needs.

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 correctly with the destructive warning and two-step mechanic, but the two-step explanation, the cancellation-email fact, and the 're-propose to start over' advice are each stated twice (once in the lead paragraph, once under 'When to use'). The duplication inflates the text without adding information.

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

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

An output schema exists, so the description is not obliged to detail return values, and it still names the final-state return. Combined with the side-effect inventory, the irreversibility warning, and the two-step protocol, an agent has everything needed to invoke 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 per-parameter baseline is 3. The description adds protocol-level meaning the individual schema fields do not convey on their own — the ordering of the unconfirmed preview call before confirm:true, and the requirement to obtain user confirmation in between — which is more than a restatement of the 'confirm' field doc.

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') and immediately scopes it against the family of meeting tools by describing the cancellation side effects and the 're-propose to start over' path. An agent can distinguish this from propose_meeting or reschedule_meeting 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: When plans change' plus the explicit two-step protocol (call without confirm, confirm with the user, call again) gives clear operational context. It does not explicitly name reschedule_meeting as the alternative when the user wants a different time, so it stops short of full alternative 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?

Beyond the destructiveHint annotation, the description discloses exactly what is mutated (status, canceled_at, category, reason), the side effects (subscription_events row with negative mrr_delta, account.current_arr_cents drop), the returned churn suggestion, and the mandatory two-step confirm:true protocol. This is unusually rich behavioral context.

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

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

Front-loaded with the effects before the when-to-use and example, and every sentence carries weight. The closing Acme example is illustrative but slightly verbose, keeping it just under a 5.

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

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

With an output schema present, return values need not be explained, and the description nonetheless covers effects, prerequisites, the churn suggestion, and the confirm flow. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains the confirm parameter's two-call pattern and reinforces why cancellation_category matters. It doesn't expand on opportunity_id or the category enum set beyond what the schema documents.

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 subscription') and immediately details the concrete effects (status set, event row written, ARR dropped). It is clearly distinguishable from the sibling renew_subscription and doesn't restate the title.

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' gives a clear selection context, and the destructive confirm workflow plus the retention-analysis note add practical guidance. It does not explicitly name an alternative tool or state when NOT to cancel, 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 beyond the annotations: it explains first-call freezing of the selection, replay returning stored per-row outcomes, ledger-retention bounds on retained replays, re-entry through full guard wrappers, and current CRM state being read at commit time. It adds explicit handling for execution_in_progress (poll) and execution_state_unknown (inspect CRM, never auto-retry), which no annotation conveys.

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 and organized, but the 'When to use' paragraph largely restates the first paragraph's receipt-expiry, idempotency-key, and retry guidance verbatim, which is wasted space in an otherwise dense block of text.

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

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

An output schema exists, so return values need no explanation, yet the description still covers the non-obvious terminal and retry states an agent must act on. Given the destructive, idempotent nature of the commit, nothing needed 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 already 100%, so the baseline is 3, but the description adds operational meaning: the idempotency key is normally the returned review_id and must be reused with the full selection for replay, confirm:true is the approval gate, and the selection is frozen by the first confirmed call.

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

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

States a specific verb (commit) and resource (the exact approved subset from review_proposed_updates) and immediately names the sibling that produces the input (review_proposed_updates). An agent can distinguish this from review_proposed_updates/propose_updates 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' paragraph gives the trigger (after review_proposed_updates, user has selected proposal IDs), the required arguments, and the retry rule (reuse the exact UUID and full selection). It also states when-not paths: receipt expiry blocks only a first commit, and no fresh review until an unknown result is resolved.

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

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

Annotations only declare the generic mutation profile (not read-only, not destructive, not idempotent), so the description carries the real burden and does so well: the server snapshots catalog prices, the caller never passes money amounts, pricing_mode resolves per_unit/flat with missing mode defaulting to flat, bundles expand automatically, and out-of-tier quantities or over-cap discounts are flagged rather than blocked.

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 paragraph is dense but well front-loaded. The problem is redundancy: the 'When to use' block restates the pricing/never-pass-a-price/bundling/flagging points nearly verbatim, so a meaningful share of the text does not earn 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 an output schema present and 100% schema coverage, the description only needs to cover behavior and it largely does: it explains the pricing model, discount rules, flagging, and the draft/sent lifecycle. Minor gaps remain (e.g., no mention of account/opportunity linkage requirements or permission needs), but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine semantics: discount_pct is percent-only with the server computing cents, quantity is an integer unit count, pricing_mode governs multiplication behavior, and a flat line with quantity > 1 is flagged. It does not add anything about name, notes, valid_until, or opportunity_id beyond the schema, keeping it short of 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?

The description states a precise verb and resource ('Draft a quote on an account') plus the key mechanic that separates it from sibling mutations: the caller selects catalog products and quantities while the server prices them. It clearly frames the artifact as pre-commit (draft/sent), distinguishing it from invoicing or contract tools.

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

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

There is an explicit 'When to use' section keyed to the user intent ('wants a priced quote for a customer') and a clear exclusion that invoicing and contracts happen elsewhere. However, it never names the closest siblings (update_quote, set_opportunity_products) or states when to prefer them, so routing between quote tools is still left partly to inference.

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

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

Goes well beyond the annotations: caller becomes owner unless owner_id is given, request_id replay semantics within 24h, atomic sequence saving with timing_mode/skip_weekends behavior, and the explicit side-effect disclaimer 'A sequence saves a plan; it never sends messages.' It also documents the touch sequence_tracking result states and retry guidance — rich, non-obvious behavioral context.

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

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

Front-loaded with the core purpose, but the middle is a dense run-on covering sequence/touch edge cases, and the 'When to use' paragraph restates the opening contract ('Pass object_type + a data object of its fields') almost verbatim. The short example is marginal. Length is defensible for the complexity, but there is avoidable redundancy.

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, return values needn't be spelled out, and the description still notes it returns the created record's full fresh state. Combined with the custom-vs-built-in routing, ownership, and sequence/touch specifics, coverage is strong; only minor gaps (error/validation behavior beyond the unknown-object_type note) 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 the baseline is 3, but the description adds real meaning: relationship fields take the target record's id, custom records need a display-name field, and the sequence/touch data payloads (ordered steps, timing_mode from_start/after_previous, request_id placement) are elaborated beyond the schema's generic data object.

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 and scope: 'Create a record of ANY object type.' It explicitly distinguishes itself from the folded typed create tools (built-in objects route to the same domain logic) and from update_record/delete_record by framing itself as 'the generic create.' An agent can place it without opening a schema.

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

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

Provides a 'When to use' section and states the calling contract (object_type + data). It explains routing behavior for built-in vs custom objects but never names an explicit alternative or a when-not-to-use case (e.g. when to prefer a typed create sibling). Clear context, no exclusions.

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

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

Annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false) cover the safety profile, and the description adds non-obvious behavior beyond them: the action re-enters the governance chokepoint and still respects approvals/write-scope, plus the workspace automation flag prerequisite. It stops short of describing failure modes (e.g. duplicate rule key, refused account-creating actions at runtime), so it is strong but not exhaustive.

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 dense core mechanics before the when-to-use and example. Efficient overall, though the 'When to use' plus example section restates the same use case twice, adding minor redundancy.

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 ('Returns the rule') need no elaboration. The description covers purpose, eligibility, dependencies, and the edit path, leaving nothing an agent needs to invoke it correctly 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 all five parameters are already documented in the schema, including placeholder syntax, condition operators, and the action_tool restrictions. The description largely summarizes that same content (governance re-entry, placeholder template), adding little parameter meaning beyond the schema 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?

States a specific verb+resource ('Create an automation rule') and immediately elaborates the trigger→condition→action model, which distinguishes it from sibling define_* tools like define_object, define_field, and define_pipeline. An agent can tell what this tool registers 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' clause with concrete examples (flag big deals, create a follow-up task) and a worked example. It also routes editing to the correct alternatives (update_record / delete_record on object_type 'automation'), naming where the id/key come from.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=true, idempotent=true); the description goes well beyond by explaining in-place update semantics ('only the fields you send change'), that the key and semantic role are immutable, that archiving is reversible and 'nothing is deleted', that `order` is atomic, and that changes apply immediately. This is exactly the extra behavioral context the annotations cannot convey.

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

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

Front-loaded with the verb/resource statement, then cleanly sectioned into update semantics, ordering, archiving, and a 'When to use' + 'Example' block. It is long for a tool description and overlaps noticeably with the already-rich schema text, which keeps it out of 5 territory.

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

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

For a 9-parameter, high-consequence mutation tool, the description covers the update-vs-create distinction, the semantic_role prerequisite, the atomic order contract, reversibility, and immediacy of effect. An output schema exists and the annotations carry the safety profile, so nothing an agent needs before invoking is missing.

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

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

Schema coverage is 100% and the parameter descriptions are themselves very detailed (color null-clearing, complete order list, position-vs-order, semantic_role per field), so the prose largely restates the schema rather than adding syntax or format meaning. The one genuine addition is the worked example tying label+semantic_role together, which is why this sits at the baseline 3 rather than lower.

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 set (add, relabel, recolor, reposition, archive, reorder) applied to a precisely scoped resource: the values of a built-in pick-list field, with concrete examples (account.lifecycle_stage, opportunity.type). An agent can distinguish this from sibling field tools like define_field or update_field 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?

The 'When to use' block gives clear triggering context (an admin wants a new, renamed, recolored, reordered or retired value) and repeats the semantic_role requirement for behavior fields. It also clarifies the order-vs-position split. It never names a sibling alternative (e.g. update_field, archive_field) or an exclusion, 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 the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds useful conditional behavior — relationship requires target_object, select/multiselect need options — and notes it returns the created field definition. However it omits auth requirements, uniqueness/failure behavior, and idempotency nuance beyond the annotation.

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

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

Front-loaded with the core action, then 'When to use' and a concrete example, which is good structure. The inline enumeration of every field_type value is somewhat redundant with the schema enum, a minor waste rather than a serious flaw.

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

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

With an output schema present, return values need no explanation, and the description covers field types, the relationship special case, options, a usage trigger, and a worked example. It is complete enough to call correctly, though it leaves creation constraints (slug uniqueness, permissions) implicit.

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

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

Schema description coverage is 100%, so each of the 5 parameters is already documented in the schema. The description restates field_type values and the target_object/options conditions, which only reinforces what the schema provides rather than adding new semantics. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Add a custom field') and scopes the target ('any object that supports them — core objects with custom fields, or any custom object'). An agent can distinguish it from update_field, archive_field, and define_object 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 explicit 'When to use' line names the trigger (an admin wants a new attribute on a core or custom object) and enumerates the field flavors. It gives clear context but names no alternative (e.g., update_field for modifying an existing field) and states no exclusions, 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 only declare readOnly=false, idempotent=false, destructive=false, openWorld=false. The description adds non-obvious behavior beyond that: admin-only authorization, the anti-sprawl check that returns matches instead of creating, the confirm_new override, and the returned object definition. These are exactly the traits annotations cannot convey.

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

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

Front-loaded with purpose, then anti-sprawl, then a scoped 'When to use' section and a worked example. It is longer than minimal for a 7-param tool, and the inline example is somewhat redundant, but every section is organized and 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?

Complexity is moderate, an output schema exists so return values need no elaboration, and the description still notes that it returns the created definition. Permissions, duplicate-handling, and the key naming side-effect ('slug becomes the stable key') are all covered, leaving no material gap.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema does the heavy lifting for label, plural, shared, icon, blurb, and confirm_new. The description adds real value for display_field by explaining its downstream consumers (entity matcher and cards), which the schema does not.

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

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

States a specific verb+resource ('Create a new custom object TYPE') with concrete examples and names the sibling operations (create_record/update_record/search_records) that act on the result. It explicitly distinguishes object types from relationship concepts, so an agent can tell it apart from define_field, define_enum_value, and the record 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' block gives an explicit trigger (admin wants to track a genuinely new noun not covered by built-ins) and an explicit anti-case (it is not a relationship type; investor/partner are stickers). It also names the anti-sprawl behavior and the confirm_new override, 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 a non-destructive, non-idempotent, closed-world write. The description adds real behavior beyond that: omitting stages seeds from the default pipeline, a type may map to only one pipeline (double-claims rejected), and it returns the created pipeline. It stops short of stating permissions, uniqueness failure handling, or reversibility.

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 verb, then a compact 'When to use' and an example. It is dense but well-organized; the only mild redundancy is re-enumerating the stage fields in prose that the schema already spells out.

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 mention is a bonus rather than a necessity. The description covers creation semantics, default seeding, and type-mapping constraints, leaving only permissions and failure modes unaddressed for a rich 4-parameter write tool.

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

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

Schema description coverage is 100%, so every parameter (label, stages, applies_to, default_for_types) is already documented in the schema. The prose largely restates the stage object shape and role enum that the schema already provides, adding only marginal synthesis ('new deals of a mapped type start on it'). Baseline 3 is correct.

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+resource ('Create an additional pipeline (a named stage sequence)') and scopes it to 'opportunities or a custom object'. This is clearly distinguishable from sibling write tools like update_pipeline and archive_pipeline, which modify or remove rather than create.

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' clause names the scenario (a motion needing its own stage sequence, e.g. an investor raise separate from the customer pipeline) and is reinforced by a concrete example. It does not, however, name update_pipeline/archive_pipeline as the alternatives for an existing pipeline, so the routing 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 disclosing the mutation lifecycle: programs are define-only, no update or archive verb exists, an admin edits them in Settings, and describe_schema lists them with ids. It also states the return value. This is exactly the kind of non-obvious behavioral context annotations can't 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, then detail, then when-to-use and an example. The first paragraph is dense but every sentence earns its place; slightly long but no filler. Structure is scannable.

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

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

Given an output schema exists (so return values needn't be detailed) and a nested membership_spec, the description covers the mutation safety profile, the no-update/archive constraint, where to edit later, and how to enumerate existing programs. 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 baseline is 3, but the description adds real semantic value – applies_to 'lists the object keys it claims' and membership_spec 'decides which records land in it', with the claim/match logic reinforced by the schema. The description reinforces rather than merely repeats the schema.

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

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

States a specific verb+resource ("Create a top-level program") and immediately disambiguates by defining a program as a parallel workstream peer of the built-in Revenue motion, distinguishing it from sibling definition tools like define_pipeline and define_object. An agent can tell what it makes 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?

Provides an explicit "When to use" line with concrete triggers (IR, Partnerships running alongside Revenue) plus a worked example. It doesn't explicitly contrast against define_pipeline/define_object as alternatives, but the define-only framing in the body clarifies the boundary well.

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, idempotentHint=false and readOnlyHint=false, so the safety profile is partly covered. The description adds real constraint context (system-owned ARR/renewal fields are refused as targets; source must be a custom object) and states that it returns the created rollup. However, it never explains the destructive/idempotency implications — e.g. what happens to existing target-field values or whether re-using an existing key overwrites or errors — which is the most consequential behavior for a non-idempotent, destructive-flagged creator.

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: purpose, then key constraints, then the edit/edit-path routing, then when-to-use and an example. The one blemish is redundancy — the usage-revenue example appears twice (in the first sentence and again in the 'Example' line) and the agg enum duplicates the 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 an output schema present, return values need not be explained (though it says 'Returns the created rollup' anyway), and the description covers creation intent, constraints, and the edit/delete path. The remaining gap is the non-idempotent lifecycle (what happens when the key already exists) and the source_object scope discrepancy with the schema.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters in detail; baseline is 3. The description's parameter content is mostly redundant ('agg is sum/count/avg/min/max' restates the enum), and it introduces a mild inaccuracy: 'The source must be a custom object' contradicts the schema, which explicitly allows source_object='account' with agg_field limited to current_arr_cents. It adds little meaning and slightly over-restricts.

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 gives a specific verb+resource ('Create a derived-metric rollup that aggregates a custom source object onto a target field') plus a concrete formula-shaped example (usage_revenue = sum of usage records onto an account field), so the agent knows exactly what artifact is produced. It also distinguishes the create path from the edit path by naming update_record/delete_record for existing rollups.

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 (an admin wants a computed field) and explicit routing for the alternative case: 'An existing rollup is edited with update_record / delete_record on object_type "rollup" (its id and key come from describe_schema).' This is exactly the when-to-use / when-not-to-use / alternative-tool guidance the dimension asks 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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: the two-call confirmation flow (first call returns a prompt, second with confirm:true), that it only sets deleted_at and never hard-deletes, cascade behavior for quote line items, what is retained for restore, and the refusal-with-counts behavior for accounts.

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

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

Well front-loaded, but the 'When to use' paragraph largely restates the opening paragraph almost verbatim (soft-delete, confirm:true, contact history retained, account removal, subscription exception), so a meaningful share of the text is duplicated rather than additive.

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, multi-object tool this covers the destructive mechanics, the confirmation handshake, cascade and retention behavior, and the refusal conditions; an output schema exists and the description still notes the return ('the archived record'), so nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: the semantics of confirm (a deliberate second-call gate, not just 'Boolean (true/false)') and the object_type acceptance/refusal rules including the admin-only rollup/automation case and the refused subscription.

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 (soft-delete) a record by object_type + id.' It explicitly carves itself out from siblings by naming cancel_subscription, update_record, and update_quote as the correct paths for cases this tool refuses, so an agent can distinguish it without opening another schema.

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

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

Has a dedicated 'When to use' block plus explicit exclusions: subscription does not remove this way (use cancel_subscription/update_record), a single quote line item cannot be deleted (use update_quote), and an account is refused while live records exist with the next-step guidance. This 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 cover readOnly/destructive/openWorld, so the bar is lower. The description adds genuinely useful context: it is the 'transparency front door, open to every role,' while schema changes remain admin-only — an access-control distinction not present in the annotations. It does not explain output volume or cost, which is the only notable gap.

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

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

Front-loaded and sectioned, but the 'When to use' paragraph restates the entire contents list from the opening sentence almost verbatim, adding length without new information. The example question is useful; the duplication is waste that undercuts conciseness.

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 needn't be spelled out, yet the description still maps what's discoverable (objects, fields, values, relationships, pipelines, motions, qualification). Combined with the access-control note and the pre-read/pre-write timing guidance, 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly signals a parameterless, whole-workspace call ('in one call'), leaving no parameter ambiguity.

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 (describe/learn) and resource (CRM workspace schema), then enumerates exactly what it returns: objects, fields (built-in + custom), valid values with semantic roles, FK relationships, pipelines/stages, motions, and qualification framework. An agent can distinguish this from schema-mutating siblings like define_object or update_field at a glance.

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

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

Explicit 'When to use' guidance: read this before reading or writing, and it notes that changing the schema stays admin-only. However, it never names the closest read-oriented alternatives (get_context, show_workspace_setup) so the agent must infer which descriptive tool to pick.

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 the annotations: the single audited egress path, the returned payload (CSV text + row count + filename), refusal of dashboard/segment ids, and the fact that every export writes a report_runs row and an audit_log event. That logging disclosure is slightly at odds with readOnlyHint=true, which keeps this from a clean 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-loaded with the core behavior and return format, and reasonably sized. The dedicated 'When to use' block largely restates the opening paragraph, which is mild redundancy rather than filler.

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

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

With an output schema present and full schema coverage, the description need not explain return values, and it still does so helpfully. Given the complex nested ReportSpec parameter and the read-only/audit nuance, one could ask for a bit more (e.g., limits/pagination semantics), leaving this just below complete.

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

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

Schema description coverage is 100%, so the schema already documents report_id, its precedence over definition, and the inline ReportSpec. The description adds only marginal framing ('give this or an inline ReportSpec'), 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 (export), resource (one saved analysis's results), and output format (CSV), plus the mechanism (audited egress path). This is clearly separable from siblings like run_report and schedule_report without opening either schema.

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

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

Gives explicit when-to-use and a concrete when-not ('a dashboard is not one CSV') with redirect guidance (pick a linked panel's source analysis or an inline panel's spec). It does not name a sibling alternative by tool name, so it falls just 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 beyond the annotations by disclosing merge semantics ('any field omitted is left untouched'), the distinct failure modes (unknown feature key skipped and named vs. template key refused), and the expected_active_motions guard returning updated:false. This is meaningful behavioral context for a destructive, non-read-only operation.

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

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

The core purpose is front-loaded, but the 'When to use' paragraph repeats the first paragraph's omission rule ('anything omitted keeps its default' vs 'any field omitted is left untouched'), and the example line is thin. Some redundancy blunts the 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?

Given nine parameters, nested objects, and an output schema, the description covers the key semantics (omission behavior, template ordering, guard) and need not explain return values. The trigger context is present, though the destructive/overwrite implications for pipeline_stages could be spelled out more.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters. The description's notes on active_motions, feature_templates ordering, and unknown-key handling largely restate the schema descriptions, adding only marginal value. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Commit onboarding answers into the workspace config,' which is more specific than a generic update. It reads as the onboarding-finalization step rather than a general workspace update, though it never explicitly contrasts with the update_workspace sibling.

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

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

Provides a clear trigger condition: 'Call at the end of the interview once the user has confirmed the choices.' However, it names no alternatives or exclusions (e.g., when to use update_workspace instead), so the when-not-to-use side 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 cover only the safety profile (readOnlyHint, idempotentHint=false, destructiveHint=false), and the description adds substantial context beyond that: nothing is held yet, co_host_emails is workspace-members-only with silent drops surfaced via dropped_co_hosts, starts_at/ends_at are opaque identifiers that must not be reformatted, and confirmed times are final. Card-vs-no-card reply behavior and the signed_in_as guide pointer further enrich behavioral disclosure.

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

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

Purpose and the holds/alternatives constraint are front-loaded, and the block is well-organized into modes, rendering rules, and a guide pointer. It is dense and long for a tool, with some overlap against the already-rich schema descriptions, but the length is largely justified by the three-mode workflow.

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, three-mode scheduling tool with an output schema, the description covers the full lifecycle: search, swap, commit, the finality of confirmed times, and the hand-off to propose_meeting. With the output schema handling return-shape details, nothing an agent needs to invoke 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 description coverage is 100% and the schema itself already documents the mode mechanics, the never-reformat rule, workday hour overrides, and target failure behavior. The description largely reinforces these constraints rather than adding new syntax or semantics, so the baseline 3 for full schema coverage is appropriate.

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

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

States a specific verb+resource (find three meeting times on the host's calendar) and precisely describes the output: three slots labeled "1"/"2"/"3", chronological, each with a rationale. It cleanly separates itself from propose_meeting ('places the holds') and from search/reschedule siblings, so an agent can route without opening another schema.

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

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

Explicitly defines when to call it (first step of booking), when NOT to call it ('never call find_times again to validate, swap, commit or re-render'), and names the alternative (propose_meeting). It also enumerates the three modes (FRESH/SWAP/COMMIT) with their triggering conditions and a worked 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 establish the safe-read profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description nonetheless adds real behavioral value: 'Reading never activates a company' pre-empts a plausible side-effect fear, and it explains the null case (existing pricing contract, billing unchanged), which is not derivable from annotations or schema.

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

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

Front-loaded with the core purpose, then states, then the null caveat, then when-to-use and an example. Every sentence carries information, though the sentences are dense and the null clause is a slight interruption to the primary flow.

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

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

An output schema exists, so return-value explanation is not strictly required, yet the description still summarizes the returned quote, capacity, approval flag and blockers. Combined with the read-only annotations, an agent has everything needed to call it correctly; only the sibling-routing gap keeps it from a 5.

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

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

Schema description coverage is 100% and the single `account_id` parameter is fully documented in the schema, including its provenance ('from a previous read or search_records'). The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Review a company's billing state') and enumerates the states it can report (free prospect, paid active, free archived), so the agent knows exactly what it returns. It does not, however, explicitly differentiate itself from the sibling `manage_company_billing`, which is the nearest alternative an agent might confuse it with.

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

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

Provides an explicit 'When to use' trigger ('Before activating or archiving a company') plus a concrete example ('What would activating this company cost?'). It gives clear positive context but names no alternatives or when-not-to-use conditions, so it stops short of routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description goes well beyond them: it warns that context_coverage may mark sections complete/truncated/unavailable/unknown, that missing sections are not evidence of absence, that bounded lists must not be called exhaustive, and that the linkedin_thread_identity type is gated and returns only a public profile mapping. These are non-obvious behavioral caveats an agent would otherwise guess wrong.

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 default behavior, which is good, but the 'When to use' section largely restates the opening paragraph ('Defaults to an account' and 'Prefer this over search_*' both appear twice), and the LinkedIn branches make the block long. The content earns its place individually, but the duplication costs structure points.

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 six-parameter, multi-mode, read-only tool with an output schema already covering return values, the description supplies the routing logic, the per-type behavior, the ambiguity-handling flow, and the coverage caveats. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, but the description adds real semantic value: account_id as an alias for {type:'account', id}, that linkedin_url never resolves by name and returns candidates on ambiguity, and the multi-step flows for linkedin_conversation and linkedin_thread_identity.

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 and resource ('Single-call bounded context for reasoning about a record') and enumerates exactly what comes back for the default account case (account row with ARR/lifecycle/renewal, subscriptions, 90 days of subscription_events, open opportunities, contacts, touches, tasks, notes). It also clearly distinguishes itself from siblings by naming search_* as the alternative it replaces.

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

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

It explicitly states when to use it ('When the user asks anything broad about a record'), names the alternative ('Prefer this over individual search_* calls'), and gives a concrete trigger example ('tell me everything about Acme'). Per-type routing (account_id vs type+id) and the LinkedIn special cases are also spelled out.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false), so the lower bar applies. The description adds substantial behavioral context beyond annotations: the grounding rule (answer only from returned articles, cite titles, never guess), the confidence/failure path (if confident is false, direct to hello@capable.run), and the article_key fallback behavior. Only the diagnostics semantics are lightly covered.

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?

Content is front-loaded and well-structured, but the description is quite long with redundancy: the opening paragraph's parenthetical examples are repeated almost verbatim in the 'When to use' block, which adds bulk without new information.

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

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

An output schema exists, so return format need not be explained; the description correctly focuses on what the agent must do (grounding rule, citation requirement, failure path, follow-up behavior). Given the number of sibling tools and the risk of CRM/help confusion, this is thorough.

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 documents all three parameters in detail. The description still adds meaningful semantics on top: article_key fetches a specific article and an unknown key falls back to searching it as a query, and the diagnostics parameter's read-only nature and setup-fact limits are reinforced.

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

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

Opening sentence states a specific verb (Answer a question) and resource (Capable's own help knowledge base), with examples that make the scope unmistakable. It explicitly distinguishes itself from sibling tools get_context and search_records, which handle the user's CRM data.

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

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

Gives an explicit when-to-use section with concrete triggers ('how Capable ITSELF works — setup, how-to, or troubleshooting'), explicit exclusions (NOT for CRM data; use get_context/search_records instead), and an example. Nothing is left to inference.

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

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

Annotations already establish read-only/safe/idempotent=false, and the description goes well beyond them: it defines lens membership as derived from stage role not label, defines sales_boundary_stage, states that pipeline filtering touches only the opportunity breakdowns while revenue/renewals/at-risk stay workspace-wide, and discloses the 500-item renewal cap with coverage{complete|truncated} and truncation semantics. It even pre-empts a misuse ('Nothing predicts').

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 return contents, which is good, but it is an unusually long, densely packed block that repeats the pipeline-filter scoping rule twice (main body and 'When to use'). The example 'Give me a pipeline summary.' adds no information. Functional but noticeably padded.

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

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

For a zero-required-param, high-complexity aggregate tool with an output schema, the description covers domain preconditions, filter semantics, result segmentation, and truncation behavior. An agent has everything needed to decide when to call it and how the filter changes the result.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema lacks: that the pipeline filter applies ONLY to the opportunity breakdowns while revenue/renewals/at-risk remain workspace-wide, and what omitting both keys yields (default pipeline + unassigned). Precedence of pipeline_id over pipeline_key is already in the schema, so the description's added value is partial rather than complete.

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 gives a specific verb+resource ('Aggregate roll-up of the workspace's opportunities and revenue') and the body enumerates exactly what is returned (stage/type breakdown, pipeline_by_lens, revenue roll-up, renewals, at-risk accounts). It is very clear what the tool produces. However, it never names or contrasts itself against adjacent read tools like run_report or export_report, so sibling differentiation is left to inference.

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' section with domain ('The Revenue sales pipeline'), a precondition ('never before a workspace has chosen its motion'), and a when-not ('Don't reach for it to answer a vague show me my data'). This is strong guidance. It stops short of naming the alternative tool to use for those rejected cases, so it is not 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?

Beyond the readOnly/destructive/openWorld annotations, the description discloses that `type` is a forgiving hint resolved against the true type, that admin-only governance records resolve by id, and critically that stale/unknown/malformed ids return {found:false} plus a fresh search rather than an error. These are substantial behavioral traits not present in structured fields.

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

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

Front-loaded with the core purpose, then edge-case behavior, then usage guidance. The long parenthetical type enumeration is dense but earns its place by defining the valid `type` space; overall efficient with minimal waste.

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-value documentation is not required, yet the description still conveys the important {found:false} failure shape and the resolve-by-id guarantee. Nothing needed to call this tool 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% (baseline 3), but the description adds real semantics beyond the schema: `type` is an optional hint that need not match, and the valid type space is enumerated. `include_archived` is left unexplained, so it does not fully cover all params.

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

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

States a specific verb+resource and scope ('Fetch the full detail of any record by id'), and differentiates itself from siblings by noting it retrieves without searching and is 'less common than search_* tools'. An agent can distinguish it from search_records and update_record without opening a schema.

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

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

Explicit 'When to use: When you have an id and want the full record without searching' gives a clear triggering condition, and it routes governance-record listing to search_records. It stops short of naming a full alternative/negative case for each object type, 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?

Annotations only cover the basic write-safety profile (readOnly=false, idempotent=false, destructive=false). The description adds genuinely non-obvious behavior: auto-filed recorder/scheduler meetings, the request_id+occurred_at durable-retry contract, and the sequence_action side effect that advances an enrollment step and returns sequence_tracking. The retry note does not contradict idempotentHint=false, since durability depends on supplying request_id.

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 clear paragraph breaks for preconditions, duplicate handling, retry, and sequencing. It is dense and long, and the 'Example' line adds little an agent needs for invocation, but nearly every sentence carries operational information.

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

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

For a 14-parameter mutation tool with nested objects and an output schema already documenting the return, the description covers the remaining gaps an agent needs: required linkage, id resolution, duplicate/sequence side effects, and retry semantics.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: why request_id exists (durable retry), the outbound/contact/occurred_at prerequisites for sequence_action, and the prohibition on the reserved capable_sequence_action custom-field key.

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 (Record) and enumerated resource types (call/email/meeting/LinkedIn), and routes to distinct siblings (search_*, propose_updates, commit_reviewed_updates) so an agent can separate it from add_note, update_record, or propose_updates.

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 ('After any meaningful interaction'), explicit precondition (MUST link to at least one account/contact/opportunity), explicit anti-pattern ('never invent ids'), and a dedicated duplicate-handling path telling the agent not to stop at 'already logged' but to process and propose updates.

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 destructiveHint=true, readOnlyHint=false and non-idempotency. The description goes well beyond: it enumerates honest execution outcomes (applied, failed with reason, expired, uncertain-but-decision-stands), explains the confirm:true gate and no-op preview, discloses admin-only access, and states two invariants (no self-decision; the queue never queues its own operations). This is exactly the behavioral context the agent needs for a destructive, non-idempotent operation.

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?

Content is front-loaded (purpose, then per-action semantics, then invariants, then usage and an example), and every clause carries load-bearing detail. It is nonetheless a dense, long single paragraph, and the trailing 'When to use'/'Example' lines partly restate the intro, costing some tightness.

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

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

For a 6-parameter, multi-action, destructive tool this is complete: it covers permissions (admin-only), safety (confirm gate), execution semantics (applied/failed/expired/uncertain), decision constraints, and self-policy behavior. An output schema exists, so return-shape detail is correctly left out, and nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: the confirm:true requirement implies 'without it the call changes nothing and returns a preview naming the tool, target, requester and age', id is ignored by list, note stores with either decision, and status scopes the list. That exceeds what the field descriptions convey.

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 resource (the workspace's governance approval queue) and explains its origin (requests a require_approval policy captured instead of running). The three actions are individually defined — list returns pending plus recently decided requests; approve records the decision then runs the captured call as the requester; deny closes it without running. An agent can distinguish this from every sibling (e.g. cancel_subscription, manage_members) without opening another schema.

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

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

A dedicated 'When to use' block states the trigger (an admin viewing or deciding queued requests from the conversation rather than Settings → Governance) and the effect (approving runs the captured action). It also gives two hard exclusions: the requester can never decide their own request, and a require_approval policy on this tool blocks rather than queues it. Alternative paths and negative conditions are both explicit.

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

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

Annotations only declare destructive/idempotent/not-readOnly; the description adds the real behavioral story: activation degrades to a pending human approval request when no administrator-granted automation budget exists, revision or price drift causes refusal, and archive/restore are impossible here. This is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with the core action and constraint, then a clean when-to-use block. It loses a point for the trailing example sentence ('Activate this company using the reviewed price, or request approval if needed'), which restates the body and earns nothing.

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, gated mutation with an output schema present, the description covers the decision path (budget vs. approval), the failure modes (stale revision, price mismatch), and the operations it refuses to perform. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by binding the parameters to an upstream call: the revision and price must be the exact quoted values from get_company_billing, in the billing currency's minor units, and must never be guessed. That workflow-level coupling is not obvious from the schema 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 and resource ('Activate a company ... request human approval for activation') and immediately distinguishes itself from the read-only sibling by requiring a prior get_company_billing review. It also carves out what it is not: archive/restore and annual capacity purchases.

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 section plus negative guidance ('Never invoke this merely to read, enrich, import or qualify a company') and named alternatives (web panel for archive/restore, separate billing-admin action for capacity). The preconditions — reviewed quote, automation budget — are spelled out.

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

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

With annotations only declaring destructive/openWorld/non-idempotent, the description carries substantial extra weight: ten-minute preview expiry, idempotency per receipt, the confirm:true gate, revision/connected_at conflict semantics, the verified:false fallback with no profile_url, and the exact blast radius of remove_history (messages and teammate access removed, published CRM notes retained). That is far more than the annotations 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?

The length is defensible for a ten-action state machine, and purpose plus the 'When to use' line are front-loaded. However, the middle is a single dense run-on paragraph covering all ten actions with no grouping or bullets, which makes the action/precondition mapping harder to scan than it needs to be.

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

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

An output schema exists, so return values need not be described, and the annotations cover the safety profile. The description still supplies everything else an agent needs: action inventory, required confirmations, preview/receipt lifecycle, conflict detection, and privacy guardrails ('never infer consent from private message text').

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-parameter workflow meaning the schema cannot express: which fields pair with which prepare/save step, that receipt replay is per-receipt idempotent, and that revisions must match what get_context displayed. It does not re-document individual field types, which 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 first sentence names the resource and scope precisely ('manage one of the user's own LinkedIn conversations'), and the body spells out the ten distinct actions (contact linking, sync on/off, teammate access, note publishing). It clarifies the boundary ('These controls never send LinkedIn messages'), though it never names a sibling such as add_note to distinguish note publishing from generic note tools.

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

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

There is an explicit 'When to use' clause enumerating the four use cases, plus a concrete example, and the narrative dictates the ordering constraints (prepare_contact before save_contact, explicit confirmation before save). It stops short of naming an alternative tool to use instead when the conversation is not the right target.

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 (destructiveHint=true, readOnlyHint=false) by disclosing the confirm:true preview contract, last-admin protection on set_role and remove, no-self-removal, no manager loops/self-reporting, records surviving removal with paid seat count following, best-effort invite email with `email_sent`, and admin-only access. These are exactly the mutation risks an agent needs before calling.

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 purpose before the action-by-action breakdown, and most sentences carry distinct behavioral detail. It is dense and repeats the confirm requirement three times ('Every action but list and revoke_invite needs confirm:true' plus the closing 'Every invite and change to a person asks for confirm:true'), which is mild redundancy in an otherwise efficient 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?

An output schema exists, so return values need not be explained, yet the description even lists the list fields. For a 7-parameter, 7-action admin tool, the when/when-not, confirm contract, and per-action constraints are all present — 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 meaning beyond the schema: it maps which actions require confirm, explains that a preview without confirm names the person and exact change, and clarifies role defaults and null-clearing for manager_id. This cross-action semantics isn't fully captured in the per-field schema descriptions.

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

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

States a specific verb+resource ('Administer who is in the workspace') and then enumerates all seven actions (list, invite, resend_invite, revoke_invite, set_role, set_manager, remove) with their exact effects. An agent can distinguish this from sibling admin tools like manage_company_billing or manage_approvals 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?

The 'When to use' paragraph explicitly covers seeing members, inviting/re-inviting, withdrawing invites, changing roles/reporting lines, and removing — all 'from the conversation instead of Settings → People.' It also states a clear when-not: leaving or switching your OWN workspace stays in the browser because the connection is bound to one membership.

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/destructive/idempotent/openWorld hints; the description adds far more: read-vs-write authority per action, hard limits (5000 rows, byte caps), skip-on-identical-identity and no-duplicate replay semantics, manual collision resolution, and that historical imports emit no automation events or enrichment. This is exactly the kind of context annotations cannot carry.

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

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

Front-loaded with purpose and the workflow, but the body is a dense semicolon-heavy block that restates some schema-level alias and enum detail. Given 7 actions and 13 parameters the length is partly justified, yet structure and readability suffer.

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

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

With an output schema present, return values need no explanation; the description still covers auth, limits, idempotency, ordering, caveats and alias handling. Nothing an agent needs to invoke it correctly 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 the baseline is 3, but the description adds real meaning beyond the schema: snake_case aliases for camelCase keys, money defaulting to integer minor units, multiselect serialized as JSON-array strings, and page-size behavior. These go beyond what the field descriptions state.

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 (import) and resource (CRM CSV exports) with named sources (Salesforce, HubSpot, Attio, csv) and the administrator persona. No sibling tool does bulk import, so it is easily distinguished from create_record, commit_reviewed_updates, etc.

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

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

Gives an explicit 'When to use' line plus the full ordered workflow (describe → preview → stage → start, with status/list for inspection and run as legacy). It also names the conditions that block use (per-record approvals, custom objects, workflows, attachments) so the agent knows when NOT to reach for it.

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

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

Annotations already mark this non-readOnly, non-idempotent, open-world, non-destructive, but the description adds substantially beyond them: holds are tentative/opaque/reversible/auto-released on expiry, "this tool itself NEVER emails anyone," the drop-and-relay edge case for non-member co-hosts, and the authorization semantics (the content okay IS the go-ahead). Rich, non-redundant behavioral disclosure.

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

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

Long for a description, but front-loaded with the highest-value facts (holds, never-emails, authorization) and each paragraph encodes a distinct rule rather than filler. The separate "When to use" block partially restates the opening, which is the main redundancy cost.

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 16-parameter, multi-step scheduling tool the description covers sequencing (find_times → propose → same-turn send), edge cases (shareable mode, hold-it case, dropped co-hosts), and authorization. Output schema exists, so return values need not be described — the completeness bar is met.

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 most parameters in detail; much of the description's param text (names out of topic, second-person agenda, workspace-members-only co-hosts, byte-identical slots) duplicates it. The additive value is the workflow guidance not in the schema: relay dropped_co_hosts, resolve ids via search first / never invent them, and the busy_override heads-up protocol.

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 the meeting") and immediately qualifies scope: places tentative, opaque, reversible holds per (slot × host) and STAGES the invitee's pick-a-time email. This clearly distinguishes it from find_times (upstream) and send_meeting_invite (the separate send step), which it explicitly warns never happens here.

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: "After find_times, once the user has okayed the topic + agenda." Gives the when-not/alternative path too: withhold the send only if the user said to hold it or in shareable mode. Nothing is left to inference, and the mandatory confirmation gate is spelled out.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces and extends this: proposing is the read-only step, writes are gated behind review/commit. It discloses non-obvious behavior beyond annotations — that matched_entities already resolves and includes ids/state/history, that source_touch_id pins authoritative records (pinned:true) which should override name-matched rows, and that entity matching is heuristic with unresolved/ambiguous candidates reported by entity_resolution.

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 purpose and the workflow sequence, and most sentences carry distinct operational information (precedence rules, don't-re-find warnings, deprecation of the transcript alias). However it is a dense wall of text with heavy capitalization emphasis that could be tightened without losing meaning.

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

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

With an output schema present, return values need not be explained, and the description still covers the full flow, downstream handoffs, edge cases (stored-touch transcripts, ungrounded ids), and the distinction between this tool and the write tools. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: it explains source_touch_id's pinning/precedence semantics, why candidate_names should be supplied for lowercase/uncased-script names, and that text may be omitted when source_touch_id names a touch with a stored transcript (returned as source_touch.transcript).

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

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

The description states a specific verb+resource and scope up front: a 'source-to-updates flow' that takes ANY source text and returns reasoning context (matched accounts/contacts/opportunities, workspace schema, recent history). It clearly distinguishes itself from siblings review_proposed_updates, commit_reviewed_updates, get_context, and the search_* tools.

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

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

Explicit when-to-use ('After any meaningful conversation, email, or note about a relationship'), plus explicit when-not and alternatives: do NOT call get_context or search_* to re-find records already resolved, and do NOT call write tools yourself. It names the downstream sequence (review_proposed_updates with ALL proposals, then commit_reviewed_updates with the receipt and selected IDs).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the transcript auto-files onto the matching account/contact/opportunity, and the tool refuses to schedule or dispatch if the workspace admin hasn't enabled Meeting recorder. It doesn't say whether a recording can be undone or what the bot does on failure, hence 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 action, then covers inputs, side effects and the admin prerequisite, then closes with a short 'When to use' block and example. Every sentence carries information (mode selection, prerequisite, auto-filing) with no filler.

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

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

An output schema exists, so return values need no explanation. The description covers the gate (Meeting recorder enabled), the side effect (transcript auto-filing), the three invocation modes and when to prefer ad-hoc over auto-record, which is everything 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 is 3, but the description adds precedence semantics the schema does not: meeting_url takes a call happening now, match books the first matching join-link meeting in the next 24 hours, and supplying neither schedules the very next join-link meeting. That mode-selection logic is real added meaning over the per-parameter 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?

Names a specific verb+resource ('Send the Capable notetaker bot to a video call' / record a meeting) and clearly separates itself from adjacent siblings like stop_recording, propose_meeting and send_meeting_invite by describing dispatching a bot to a live or upcoming call. The purpose is unambiguous without opening the schema.

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

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

Explicitly states the routing condition: use for ad-hoc recording, auto-record covers scheduled meetings, and it explains the three input modes (meeting_url for a live call, match for a specific upcoming meeting, neither for the next meeting with a join link). It names the alternative mechanism (Auto-record) and gives a concrete example.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds materially: it is a hard delete with no undo/history, the linked entities survive, and critically it documents the two-step confirmation flow ('call again with confirm: true'). That confirmation protocol is not derivable from the annotations or schema and prevents an agent from firing a destructive call without user sign-off.

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 destructive warning and the confirm protocol, then when-to-use, then an example. Every element is useful, though the example sentence partially restates the 'when to use' rationale rather than adding new information.

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

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

An output schema exists so return values need not be explained; the description covers purpose, destructive semantics, the confirmation handshake, and usage timing. Nothing an agent needs to invoke this 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% and account_id/contact_id are self-evident uuids, so baseline is 3. The description adds real meaning on the confirm parameter, explaining it is a two-phase safety gate rather than a plain boolean, which the schema's 'Boolean (true/false)' line does not convey.

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 ('Unlink a contact from an account') and immediately disambiguates scope: the contact and account records themselves are kept, only the M2M row goes. An agent can distinguish it from add_account_contact and from delete_record 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' line gives the triggering condition (someone leaves the company or their role ends) plus a concrete example. It does not explicitly name the alternative tool for the inverse/replacement case, so it falls just 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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it writes a subscription_events row of type 'renewed', performs cadence-based term-date math, and notes the free-text note lands on the event row and not the subscription. It stops short of mentioning auth/permission requirements or failure modes, so a 4 rather than 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?

It is front-loaded and broken into three short, purposeful parts (what it does, when to use, a concrete example). The example sentence is genuinely useful for an agent but slightly lengthens the definition, so it lands just below the tightest possible phrasing.

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

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

With an output schema present, return values need not be explained, and the description covers purpose, trigger, term math, and param rationale. It omits edge cases such as what happens on an already-renewed or cancelled subscription, leaving a minor gap for a mutation tool.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description adds semantic rationale the schema lacks — that optional mrr_cents/seats/plan_name updates exist 'for renewals with uplift' and that opportunity_id should be linked 'when available' — which helps the agent decide whether to populate optional fields.

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 ('Renew a subscription') and immediately scopes the operation: advancing term dates by one cadence, optionally updating MRR/seats/plan, and writing a 'renewed' subscription_events row. This is specific enough that an agent can distinguish it from sibling cancel_subscription 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?

It gives an explicit trigger ('When to use: On close-win of a renewal opp') and clarifies that term-date math is handled automatically by cadence. It does not name or contrast a competing sibling tool (e.g. cancel_subscription), so it stops short of full when-not/alternative guidance.

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

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

Far exceeds the annotations: discloses that the same event/link/invite is preserved, that an invitee email is sent, that the new time is freebusy-checked against every host and refused if busy, that host workday/buffers/min-notice are NOT re-applied, and that the user should confirm first since it edits a live event. This gives an agent the full mutation side-effect picture consistent with destructiveHint=true.

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 and readable, but the closing 'When to use' block largely duplicates the opening paragraphs (same-event-in-place, invitee note, confirmed-only, freebusy check), so a meaningful chunk of text does not earn its place.

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

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

For a mutation tool with an output schema, the description covers everything an agent needs: preconditions, side effects, validation behavior, and the routing decision versus siblings. Nothing relevant is left unspecified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: new_start is an ISO 8601 instant obtainable from find_times or a user-named time, and duration is preserved unless new_duration_min is passed. It doesn't restate the schema, it enriches the decision logic around the parameters.

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

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

States a specific verb and resource with scope: 'Move an ALREADY-CONFIRMED (booked) meeting to a new time, in place', and immediately clarifies it patches the SAME event with the SAME link and attendees. This distinguishes it cleanly from cancel_meeting, propose_meeting, and find_times.

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

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

Explicitly says 'Use this ONLY for a confirmed meeting' and names the correct alternative path for unconfirmed meetings ('cancel it and propose new times instead'), plus the not_confirmed error behavior. It even supplies trigger phrasing ('move my 2pm to Thursday').

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

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

Annotations only declare the mutation/safety profile (destructiveHint, idempotentHint, readOnlyHint=false); the description goes well beyond by disclosing the exact side effects (account links and touch/note/task history return intact because delete retains them; contacts/opportunities/subscriptions re-link via retained account_id), the refusal path for non-deleted or unknown ids ('refused with the reason and nothing changes'), and the auth scope.

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 well-sectioned, but the 'When to use' paragraph substantially restates the opening paragraph (restorable objects, undo semantics), which is mild redundancy rather than waste.

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

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

Output schema exists, so return-shape detail is not required; the description nonetheless names the restored:true marker. With error semantics, side effects, id source, object restriction and permission scope all covered, nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including that object_type is one of contact|account and that id is a uuid. The description reinforces the id source (delete result or get_record with include_archived) but adds no new syntax or format detail, so the baseline 3 applies.

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

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

Names a specific verb and resource ('bring back a soft-deleted contact or account') and positions itself explicitly as 'the undo of delete_record', which cleanly separates it from delete_record, get_record and create_record in the sibling list. Scope is bounded to two object types.

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

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

Gives explicit when-to-use ('Undo a delete'), names when NOT to use it ('the other objects have no undo (re-create them)'), and routes the agent to the prerequisite tool ('Find a deleted record with get_record(include_archived:true)'). It also states the permission scope is the same as delete_record.

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