Saybooks

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-obvious behavior: the account set is fixed, some accounts may exist in use without a mapping, and the tool will not invent a mapping for those — the agent must escalate instead. It does not describe the shape of the returned map, but that gap is modest.

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

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

Two short sentences, the usage rule front-loaded, and the escalation constraint stated in the same breath. Nothing is repeated from the title or annotations.

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

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

For a no-param, no-output-schema read with full annotation coverage, the description supplies the two things an agent actually needs: when to call it and what to do about unmapped accounts. It could say slightly more about what the returned mapping looks like, but that is the only real 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?

The tool takes zero parameters, so there is no parameter semantics to explain; baseline for a no-param tool applies. The description correctly implies a whole-map read with no filtering.

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 enumerates exactly what the map contains: the fixed derivation accounts, which of them the books actually use, and their ledger-of-record names. That is a specific resource with concrete contents, though it is phrased as a noun list rather than a verb, and it never names a sibling (e.g. bridge_map_account, bridge_exports) to distinguish itself from.

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

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

"Read this before any export" gives an explicit precondition for use, and the second sentence gives a clear rule for the ambiguous case (in-use but unmapped accounts get escalated to a person/accountant, not guessed). It stops short of naming the export sibling or saying when the tool is unnecessary.

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

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

Beyond the annotations (which only say not-readOnly, not-destructive, not-idempotent), the description discloses refusal conditions and who they name, the effects list (file built, hand-over recorded, link minted), retention with control totals and a hash, and a handling rule ('never relay the file's bytes'). This is exactly the mutation 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 action and effects summarized at the end in a scannable 'Effects:' line. Slightly mannered phrasing ('Hand the period over', 'the act that says the period has been handed over') adds words without adding precision, keeping it off a 5.

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

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

For a non-idempotent write with no output schema, the description covers what is produced (a download link, not bytes), what is persisted for later audit, and what blocks the call. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a step above by explaining the consequence of omitting 'from' ('month-end becomes a diff, not a re-key') rather than just restating the schema. The multi-currency requirement for 'currency' is left to the schema, so it is not a full 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 opening clause names a concrete verb and resource ('build the file in the ledger's shape', 'return a download link') and immediately distinguishes itself from the sibling that only previews (bridge_preview). An agent can tell this is the committing export act versus bridge_preview and bridge_exports without opening schemas.

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

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

Explicit ordering rule ('Show the person bridge_preview and its totals first'), an explicit variant of the call ('Omit "from" to continue from the last hand-over'), and an explicit precondition ('Refused while an account the period uses is unmapped'). When-to-use, how-to-vary, and when-it-fails are all stated.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the description adds genuine value by disclosing what a returned row contains (control totals plus a hash) and, critically, that the link re-downloads the exact original file rather than re-deriving it. That is a behavioral guarantee an agent cannot infer from the annotations, though nothing is said about ordering or time bounds of the listing.

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 sentences, front-loaded with what it is, then the use case, then the row contract. The phrase "in which shape, through when" is slightly oblique where "in what form, up to which date" would be plainer, but nothing is padded.

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

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

With no parameters, no output schema and full annotation coverage, the description carries the remaining burden and does explain the shape of a row and the meaning of the link. The only gap is scope of the listing (all exports ever, or a window), which matters given the schema offers no filtering.

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 input schema takes zero parameters, so per the baseline this sits at 4. There is nothing extra the description could reasonably add about parameters it does not have.

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

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

States the resource precisely (what has been handed to the ledger) with totals and the outgoing file, which tells an agent this is a historical log of exports rather than a derivation. However, it never names the near-identically named sibling bridge_export, so an agent choosing between the singular and plural tool gets no help from the description.

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 rhetorical question "did the ledger get August?" gives a concrete usage scenario, which is more than most tools offer. But there is no explicit when-not guidance and no mention of alternatives such as bridge_export or bridge_preview, both of which sit in the same namespace.

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

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

Beyond the readOnly/idempotent annotations, the description discloses real behavioral traits: figures are preliminary, unreviewed rows are excluded from the numbers, unclassifiable transfer accounts surface as a question for the user, currency is limited to one at a time, and the agent must not round, restate or 'fix' figures. It also says the correct remedy is in the books, not the report. This is materially more than the annotations provide.

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

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

The core output definition is front-loaded in the first sentence and the rest is operational guidance, so most sentences earn their place. Some phrasing is ornate ('said on their face') and the presentation instruction ('Say "preliminary" when you present it') runs long, costing a bit of clarity for an otherwise tight block.

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

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

There is no output schema, yet the description explains what comes back (P&L plus balance sheet plus the notes on what is excluded), how it should be labeled, and what to do when figures look wrong. For a read-only report with zero required parameters, an agent has everything needed to call and present it correctly.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning: it mirrors the period grammar (quarter 2026-Q1, month 2026-09, year, or from/to) and adds the constraint that only one currency at a time is handled, which clarifies when the currency parameter matters. It does not explain behavior when both period and from/to are supplied.

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 specific deliverables (a profit and loss for a period plus a balance sheet at its end) and states they come from the books and are marked preliminary. The phrase 'with everything they leave out said on their face' signals that the output carries notes on exclusions, which no sibling tool (gl_entries, tax_return, inv_valuation) provides. An agent can identify this as the statement-generation tool without reading the schema.

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

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

It gives concrete trigger phrasings ('how did we do this quarter', 'generate preliminary Q1 financials', 'a number for the accountant before the close') and the accepted period formats, which is strong context. It does not name an alternative tool or state when not to use this one (e.g., when the books aren't reviewed yet, use gl_changes instead), so it stops short of full routing guidance.

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

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

The description adds meaningful behavior beyond the annotations: it states that changing a mapping never rewrites a hand-over that already went out, and closes with 'Effects: account mapping written.' The annotations already declare this is a non-read-only, non-destructive, non-idempotent write, so the description fills in important operational context. It does not cover permissions or error behavior, keeping it from a 5.

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

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

The description is front-loaded with the purpose, then transitions into usage rules, the three mapping kinds, and effects. It is somewhat long but appropriately sized for a seven-parameter mapping tool with multiple modes. Most sentences carry useful information, though a few could be tightened.

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 no output schema and seven parameters, the description covers the essential context: the three mapping kinds, what each requires, import-matching behavior, and the effect of writing a mapping. It does not describe return values or error cases, but the annotations and 100% schema coverage reduce the need for that. The definition is complete enough to support correct use.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds useful semantics by explaining what the 'account' parameter means for each kind, how code and name are used by Xero and QuickBooks imports, and that the tax rate label is only needed where the import expects one. It does not add much for parameters like note or reason, but it meaningfully enriches the most important 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 clearly explains that this tool records how something is named in the ledger of record, covering derivations, categories, and source accounts. It distinguishes itself from bridge_accounts by explaining that bridge_accounts lists mappings while this tool writes them. The phrasing is slightly indirect at the start, but the overall purpose is clear.

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

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

It gives concrete usage instructions: ask for the code and name exactly as the chart spells them, supply both where possible because Xero matches on code and QuickBooks on name. It defines the three mapping kinds and what each requires, and points to bridge_accounts for listing. It does not explicitly state when not to use the tool, but the practical guidance is strong.

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

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

Annotations already declare readOnlyHint/idempotentHint, but the description adds the substantive guarantee 'Records nothing' and describes what the response contains (control totals, unmapped accounts, first N rows). That is real behavioral context beyond the structured fields, though it says nothing about size limits or what happens when the period has unmapped 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?

Three short sentences, front-loaded with what the tool returns and the no-write guarantee before the routing instruction. Slightly awkward register ('The journal for a period in the ledger's shape') costs a point but nothing is filler.

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

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

With no output schema, the description carries the return-value burden and does so by naming control totals, sample rows and unmapped items. For a 5-parameter read/preview tool that is largely sufficient; a note on how unmapped accounts affect usability of the preview would close the last gap.

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

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

Schema description coverage is 100%, so every parameter (to, from, rows, format, currency) is already documented, including the omit-'from'-to-resume behavior. The description restates that resume rule rather than adding new meaning, 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 operation: produce the journal for a period rendered in the target ledger's shape (xero/qbo/csv), plus control totals and unmapped items. The naming of bridge_export as the follow-on action implicitly distinguishes it from the export sibling. Slightly indirect phrasing ('the ledger's shape') but an agent can tell what it gets back.

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 sequencing: 'Show the person the totals and the first rows before bridge_export' tells the agent this is a pre-flight step, not the hand-over itself. It also explains the omitted-'from' case (resume from the last hand-over in that format). It doesn't address other near siblings such as bridge_journal or bridge_financials, so 4 rather than 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), but the description adds real semantic context beyond them: both surfaces write to the same log, actor_kind 'agent' vs 'human' is decoded, and refusals are retained. It omits ordering/pagination behavior, so not a 5.

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

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

Three short sentences, front-loaded with the core question the tool answers and followed by the actor_kind legend. The closing clause ('exactly what you want to be able to review') is editorializing that could be cut, which keeps it from a 5.

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

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

The tool is a simple read with 100%-documented parameters and no output schema, so the description carries the burden of describing return shape — yet it never says what fields a row contains (timestamp, action, subject, outcome) or the default sort order. Given no output schema exists, this is a meaningful gap for an agent trying to interpret results.

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

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

Schema description coverage is 100% for both parameters (limit with a stated default of 50, subject_id with an example 'SO-0003'), so the baseline is 3. The description adds nothing about how limit interacts with truncation or what subject_id filters on beyond the schema's example.

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

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

The description answers what the tool returns — 'What happened, who did it, and whether it was a person or an agent' — clearly identifying an audit-trail read. It distinguishes actor types but never differentiates itself from nearby log-style siblings such as gl_changes or crm_today, so an agent could confuse the audit trail with a change log.

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

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

Usage is implied rather than stated: 'a blocked agent action is exactly what you want to be able to review' suggests the review/compliance use case. There is no explicit when-to-use, no when-not-to-use, and no named alternative (gl_changes, core_next_actions) that an agent should pick instead.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description earns credit by enumerating what the payload contains (seller block, tax id, payment instructions), which matters because there is no output 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?

One tight sentence with the identity-of-the-business framing front-loaded and the returned fields following. No filler, though the fragmentary noun-phrase style costs a little immediate legibility.

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

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

For a zero-required-parameter read tool with no output schema, the description adequately signals the return contents and directs the logo question to the parameter. It stops short of noting fields that may be unset or that this is the workspace-wide singleton profile.

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 single with_logo parameter carries its own clear explanation (data URL, large, otherwise type/size only). The description contributes nothing about the parameter, so the baseline 3 applies.

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

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

The description names the specific resource — the business's own identity as printed on documents — and enumerates its contents (seller block, tax id, payment instructions). It lacks an explicit verb ("get/read"), so a reader must infer retrieval, and it never names the write counterpart core_set_company_profile to draw the line between them.

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

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

There is no statement of when to call this versus core_set_company_profile or core_set_company_logo, and no prerequisites or exclusions. The read-only annotations let an agent infer that this is the read side, but the description itself gives no 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 establish that this is a non-read-only, non-destructive create operation. The description adds valuable behavioral context beyond that: zero credit limit means prepay only, not a missing value, and credit-limit changes are separately logged. It still does not cover duplicate-customer behavior or the response shape.

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

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

The description is front-loaded and appropriately brief for a create tool. The final "Effects: customer created" is somewhat redundant with the opening sentence, but it still marks the side effect explicitly.

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 create tool with full schema coverage and annotations but no output schema, the description covers purpose, a key credit-limit rule, and the creation effect. It would be stronger if it mentioned duplicate handling or whether the response returns an identifier for follow-up calls.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, including that credit_limit is in cents. The description adds meaningful business semantics for credit_limit: zero is a real prepay position and must not be fabricated. It does not clarify what happens when credit_limit is omitted, which is a remaining gap.

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

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

The description states a specific verb and resource: "Create a customer we can sell to." It also implicitly distinguishes this operation from changing a customer's credit limit later, which is described as "its own logged command."

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

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

It gives clear when-not-to guidance around credit limits: do not invent a limit to force an order through, because limit changes belong to an authorized, separately logged command. It does not explicitly name alternatives such as core_update_customer or crm_promote_to_customer, so it stops short of full when/when-not/alternative coverage.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation. The description adds useful behavior beyond that: the item is created, and stocked=false items never check or deplete inventory. It does not cover duplicate-SKU behavior or permissions.

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

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

The description is short and front-loaded with the core action. 'Effects: item created' is slightly redundant with the opening verb, but otherwise the structure is efficient.

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 creation mutation, the description covers purpose and stocked behavior but is silent on duplicate SKU handling, whether the SKU is immutable, permissions, and what is returned. With no output schema, those gaps leave the definition only minimally complete.

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

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

Schema coverage is 100%, so the schema already documents all six parameters. The description adds some operational meaning for stocked=false, but it largely overlaps the schema's existing 'False for services — never depletes' wording and adds no detail for sku, name, on_hand, unit_price, or tax_rate_bp.

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

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

The description states a specific verb and resource: 'Create a sellable item.' No sibling tool creates sellable items, so the action is unambiguous against core_create_customer, core_set_price, and the inventory 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?

Usage is implied by the purpose, and the stocked=false guidance helps distinguish item types. However, the description does not explicitly say when to use this versus alternatives like core_receive_stock, core_set_price, or inv_set_opening_cost.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world profile, so the safety bar is met structurally. The description adds real value by disclosing the data content a caller receives (address, tax id, terms, hold state) and by clarifying that credit exposure lives elsewhere, which is the main behavioral surprise for this tool. No note on error behavior for a missing/invalid id, which keeps it from 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?

Two short sentences, front-loaded with the identity of the resource and its contents, followed by the sibling disambiguation. Every clause carries information; nothing is padding.

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

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

There is no output schema, but the description compensates by enumerating the returned field groups, which is what an agent needs to decide whether this tool answers its question. The remaining gap is modest: no indication of what a not-found customer yields, but for a read-only single-record fetch the definition is sufficiently 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?

With a single parameter at 100% schema description coverage, the schema already tells the agent everything ("The customer. An existing customer id."). The description adds no syntax, format, or lookup guidance beyond what is already there, 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+resource ("One customer as master data") and immediately enumerates the fields covered (contact facts, billing address, tax id, terms, hold state). It also names the sibling that returns the complementary view (o2c_get_customer for live credit position), so an agent can distinguish the two without opening either schema.

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

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

The parenthetical routes the agent: use this for master data, use o2c_get_customer when the live credit position is needed. That is clear conditional guidance toward an alternative, though it stops short of explicit "when not to use" phrasing or mentioning core_update_customer / core_create_customer as adjacent operations.

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

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

Beyond the annotations, it discloses concrete effects ('customer.on_hold set; o2c_confirm_order refuses while held') and clarifies non-effects ('Already-confirmed orders are not touched — fulfil and bill them as agreed'). This tells the agent exactly what the mutation does and does not affect.

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 action, then explains the key behavioral constraints and effects in a tight sequence. Every sentence contributes useful context: what a hold is, what it does not touch, when to use it, and its effects.

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

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

For a two-parameter mutation tool with annotations and full schema coverage, the description covers purpose, usage conditions, side effects, and exclusions. No output schema exists, but the description explains the observable consequence (confirmations are refused while held), which is sufficient.

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 parameter meanings are already documented. The description reinforces that 'reason' is shown when the hold blocks something, but adds little beyond the schema for customer_id or reason.

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

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

The description states a specific verb and resource: 'Put a customer on credit hold.' It also distinguishes the hold from credit-limit logic ('A hold outranks the limit') and from existing order handling ('Already-confirmed orders are not touched'), making the scope clear without opening sibling schemas.

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

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

It gives clear conditions and examples for when to use the tool: 'a bounced check, a dispute turning sour, news about the customer.' It also implicitly limits use to taking on NEW exposure, but it does not explicitly name core_release_customer as the undo path or state when not to use it.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the link itself is the credential (whoever holds it acts under that name), all acts are attributed to that name, and out-of-role attempts are refused and logged. It stops short of stating token expiry, revocation semantics, or required caller permissions.

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 line front-loads the two invite paths, and the role list is compact and information-dense. The closing sentence about one-sentence denial refusals being 'reviewable, like everything else' is workspace policy padding rather than tool-specific information, slightly diluting the payload.

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

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

With no output schema, the description must carry the return contract, and 'Effects: member token minted' only half does so — it never says the minted link/token comes back in the response, which is precisely what the caller needs in order to share it. Missing too is any statement of who may call this or whether an existing member with that name is updated or rejected.

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

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

Schema coverage is 100%, so the baseline is 3, and the description does add real value by defining what each role can do (controller vs clerk vs viewer) rather than leaving bare enum names. Against that, it introduces an 'owner' role that the schema enum does not accept, which could lead an agent to pass an invalid value, and it adds nothing about the email/name interaction beyond the schema.

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

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

States a specific verb+resource (invite a member to this workspace) and immediately clarifies the two mechanisms: email invite via Google sign-in, or a member token link. An agent can distinguish it from core_members (listing) and core_revoke_member (removal) by name alone, though the description never names those siblings explicitly.

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 real guidance on choosing the email path versus the token path, and the role list helps pick a role value. However, it never says when to use this tool versus core_members or core_revoke_member, nor does it state preconditions such as who is permitted to invite or what happens if the name already exists.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well past that: it says nothing is posted or stored, re-derivation is the truth, accounts are fixed, voided invoices are excluded (INV-23), and the ledger of record owns inventory and margin. That is exactly the kind of derivation and side-effect disclosure an agent needs to reason about repeat calls and downstream reconciliation.

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

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

Front-loaded with the core statement (what it produces and who consumes it), then qualification sentences. The closing line 'The ledger of record stays wherever it is' largely restates the earlier ownership point and could be cut, but otherwise the prose is dense and purposeful.

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

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

With no output schema, the description carries the burden of explaining the result, and it does so at the level of content (revenue-side lines, fixed accounts, no COGS) rather than row shape. For a three-optional-parameter read tool with full safety annotations, that is nearly complete; a note on what a single journal line contains would close the gap.

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

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

Schema description coverage is 100%, so to/from/currency are already fully documented in the schema, including the ISO formats and the currency-summing caveat. The description adds no additional parameter semantics 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 concrete resource (double-entry journal lines derived from the books) and the intended consumer (export to the ledger of record). It does not name or distinguish itself from the plausible lookalikes in the sibling list (gl_entries, gl_changes, bridge_export), so an agent must infer the boundary rather than read it.

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

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

Usage is implied through scope statements — revenue side only, no COGS/inventory, voided invoices contribute nothing — which effectively describes what the output will and will not contain. However there is no explicit guidance on when to choose this over gl_entries or bridge_export, and no stated prerequisites such as needing books to exist first.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by clarifying that the tool includes both email members (Google sign-in) and token keys (agents, link shares), which goes beyond what the annotations provide.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the data scope without 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?

For a zero-parameter read-only tool with no output schema, the description is nearly sufficient: it explains the two access categories returned. It could be slightly more complete by indicating whether token secrets are masked or what fields are included, but the essential context is 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?

The tool takes zero parameters, so there are no parameter semantics to document. Per the scoring baseline for 0 params, this dimension defaults to 4.

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 identifies the resource ('who has access') and the two categories covered: email members and token keys. It is clear what the tool returns, though it lacks an explicit verb like 'list' and does not name sibling tools such as core_invite or core_revoke_member.

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

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

There is no explicit guidance on when to use this tool versus alternatives like core_invite or core_revoke_member. The description only states what the tool covers, leaving the agent to infer that it is a read/list operation from the tool name and annotations.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations: it returns both available commands and business reasons for blocked ones, and those reasons are meant to be surfaced verbatim to a person.

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

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

The description is short, front-loaded with the core behavior, and each sentence adds distinct value: what it returns, why it is authoritative, and how to use blocked reasons.

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

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

For a read-only, two-parameter tool without an output schema, the description explains the conceptual return value and the intended handling of blocked reasons sufficiently for an agent to call and interpret it correctly.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema. The description adds no additional parameter meaning or examples, which is acceptable but not additive at this level.

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 capability: listing commands currently available on an entity and explaining why blocked commands are unavailable. It distinguishes this from guessing at a state machine and ties the result to the same evaluation used for live UI buttons.

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

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

It gives clear usage guidance: prefer this over guessing at a state machine, and quote blocked reasons verbatim because they are user-facing. It does not name alternate sibling tools or explicitly list when not to use it, but the context is strong.

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

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

Annotations already declare the mutation profile (readOnly=false, idempotent=false, destructive=false). The description adds real context beyond that: receipts are additive and never retroactive, negatives are logged as corrections, and item.on_hand is the mutated field. It does not cover whether the item must already exist, what happens on an unknown item_id, or permission requirements, so it sits at adequate rather than rich.

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

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

Four short sentences, front-loaded with the core effect, then the non-retroactivity rule, then the correction workflow, then the mutated field. No filler and no repetition of 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?

For a 3-parameter mutation with no output schema, the description covers the effect on state and the correction path, which is the critical information. Gaps remain around preconditions (existing item id) and what the response returns, but annotations and the schema carry most of the rest.

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 meaning beyond the schema: it explains why a negative qty exists (count correction) and that such a receipt is visible as a correction in the log. It says nothing about note or item_id beyond what the schema already 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?

Opens with a specific verb and resource: "Increase quantity on hand for a stocked item." It implicitly distinguishes itself from count-correction flows by stating receipts are additive and never retroactive, but it never names a sibling (e.g. inv_count_stock or p2p_receive_goods), so the agent must infer the boundary.

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

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

Gives clear when-to-use guidance, including the non-obvious case: to correct a count, receive the difference with a negative qty. It lacks an explicit "use X instead" routing statement against the many inventory/purchasing siblings, which keeps it below a 5.

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

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

Annotations already fix the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuine behavior beyond that: the release is separately logged, a reason is mandatory because it is audited later, the credit limit re-applies from the next confirmation, and the concrete effect is 'customer.on_hold cleared'. It does not address repeat invocation, which is notable given idempotentHint=false.

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

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

The action is stated first, followed by rationale and then effects, so it is well front-loaded. The middle sentence about 'who released it and why' is slightly discursive but earns its place by justifying the required reason parameter.

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

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

For a two-parameter mutation with no output schema, the description covers state effect, audit logging, and downstream consequences. The remaining gap is error/precondition behavior — what happens if the customer is not currently on hold.

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's terse 'Why the hold is lifted': it explains that the reason is the durable audit answer to 'who released it and why', motivating a substantive value rather than a placeholder.

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-state transition: 'Release a customer from credit hold.' That is unambiguous and clearly the inverse of the sibling core_hold_customer, so an agent can select it without inspecting 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?

Usage is only implied: the tool obviously applies to a customer currently on hold, but the description never states preconditions (does it fail if the customer is not on hold?), nor does it name or compare against alternatives such as core_update_customer or core_set_credit_limit for related credit changes.

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 that this is a real execution through the actual registry with the same guards and audit trail (not a simulation), that the scratch workspace is wiped and the scenario replayed, and that persisted conformance evidence is refreshed. That resolves the ambiguity of readOnlyHint=false / destructiveHint=false / idempotentHint=false for the caller.

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

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

Front-loads the core action and the response shape, then adds effects last. It is slightly longer than needed — the 'refusal steps teach more than the happy path' aside is advisory rather than operational — but no sentence is filler.

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

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

With no output schema, the description still enumerates what the response contains (act, command, arguments, expectation, and actual result) and discloses all side effects, so an agent knows exactly what it gets back and what state it changes.

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, including the o2c default and the pointer to core_spec_status for valid file names. The description adds no parameter-level meaning 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 ('Replay one spec scenario live in its scratch workspace') plus the return shape ('step-by-step evidence'). It also distinguishes itself from the nearest sibling by pointing at core_spec_status for the scenario list, so an agent can pick correctly without opening the schema.

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

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

Gives a clear use context ('Show it to someone learning the area') and notes the refusal steps are the most instructive. It does not state explicit when-not conditions or name an alternative tool for the 'just list scenarios' case beyond the parameter hint, so it falls short of a 5.

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

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

Annotations already flag the tool as destructive, and the description adds substantial context beyond them: exactly what is destroyed, that only the current workspace is affected, the production restriction, and that fixture reseeds create an audit trail via logged commands.

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

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

The description is front-loaded with the core action and remains fairly tight. The final 'Effects:' sentence partly repeats the earlier deletion statement, but the reinforcement is useful for a destructive operation.

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, zero-required-parameter reset tool with no output schema, the description covers scope, effects, environment restriction, optional fixture behavior, and audit consequences. An agent has enough information to decide whether and how to call it.

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

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

Schema coverage is 100%, so the schema already documents the fixture parameter. The description adds meaningful semantics by explaining that fixtures are command scripts replayed into the workspace, producing an audit trail, which goes beyond the schema's brief parameter note.

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

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

The description states a specific verb and resource: 'Wipe THIS workspace and optionally reseed it from a named fixture.' It also scopes the action to the current workspace only, distinguishing it from anything global.

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

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

It clearly states a key usage constraint—available only outside production—and explains the optional fixture reseed path. It does not explicitly compare against sibling tools such as core_replay_scenario, so it falls short of full when-to-use/when-not 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 flag destructiveHint=true, so the bar is lower, yet the description adds real substance: revocation is logged, historical entries retain the member's name, and nothing is deleted. It does not address whether revocation is reversible, what happens on a second call (idempotentHint=false), or what error an unknown member yields.

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

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

Four short sentences, front-loaded with the action and its immediate effect. The trailing "Effects: member token revoked" largely restates the first sentence and is the one mildly expendable line.

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

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

For a one-parameter mutation with no output schema and full annotation coverage, the description says enough to call it safely, including that data is preserved. Gaps remain around reversibility and repeat-call behavior, which matter given idempotentHint=false.

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

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

Single parameter with 100% schema description coverage, so baseline is 3. The description never clarifies whether "name" is a display name, identifier, or token reference, adding nothing over the schema text "The member to revoke."

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

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

Specific verb + resource ("Revoke a member's token") with the immediate effect stated. It doesn't name a sibling (e.g., core_invite, core_members) to contrast with, so it falls just short of the top mark.

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

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

Usage is only implied: revoke when you want a member's link to stop working. There is no explicit guidance about when to revoke versus hold, invite again, or list members via core_members, and no stated prerequisites.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context — and it does: the payload is generated from the same registry the tools come from, so the server cannot serve a stale copy, but the client's cached connector tool list can. It then supplies the remediation (remove/re-add the connector, start a new chat). That is genuinely useful operational detail no annotation or schema 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 with what the tool returns before the operational advice, and most sentences carry distinct information. It is slightly padded — 'This schema is the truth; the tool list is a cache of it' restates the caching point already made two sentences earlier, and the connector-cache warning runs long for a zero-arg tool.

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

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

No output schema exists, but the description enumerates the payload's contents (modules, entities, lifecycles, rules, commands), states its freshness guarantee and its failure mode, and tells the agent what to do if reality diverges. For a zero-parameter read tool, an agent has everything needed to call it and interpret the result.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly spends no words on nonexistent arguments.

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

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

States a concrete verb-and-content pair: it returns the system's shape — modules, entities, lifecycles, encoded rules, and every command. That is instantly distinguishable from every sibling, which are all specific operational tools, and an agent can tell this is the introspection/meta entry point without opening anything.

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, prescriptive trigger: 'Call this first in a new session', plus the rationale ('cheaper than guessing') and a diagnostic path if a listed command is absent from the tool list. It stops short of naming when NOT to call it or a sibling alternative (e.g. core_spec_status, core_next_actions), which keeps it off 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 readOnly, idempotent, non-destructive, closed-world. The description adds genuine behavioral context that results are aggregated per module and vary with what is mounted, but it omits return format, ranking, and result limits.

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

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

Two sentences, front-loaded with purpose and scope; no filler. The second sentence's phrasing ('tracks what is mounted') is slightly indirect compared to a crisp statement of result variability.

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

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

For a single-param read tool with full annotation coverage, most needs are met. But with no output schema, the description should say more about what results look like (entity shape, per-module grouping, limits), which it does not.

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

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

The schema documents only one param 'q' as 'Free text.' (100% coverage, so baseline is 3), and the description does add meaning by clarifying that q accepts an id, name, or reference. However, it gives no syntactic detail (format of ids, partial vs exact matching), so value over the schema is modest.

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

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

States a specific verb (Find) and resource (entities) with an explicit scope (across every module), and clarifies it accepts id, name, or reference. It implicitly differentiates from the many module-scoped siblings (crm_list_contacts, gl_entries) by being the cross-module lookup, though it names no sibling explicitly.

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?

"Each module contributes its own results; what you can find here tracks what is mounted" hints at scope but never states when to prefer this over module-specific getters like core_get_customer or o2c_get_order. Usage is implied rather than directed, with 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 only declare the generic mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds substantive behavior beyond that: fetch-once-then-store (never hotlinked), a 300 KB size cap, accepted formats, the company-profile prerequisite, and the crucial fact that changing the logo re-brands past documents while frozen seller data and amounts stay fixed. It also states the effect summary.

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 intent is front-loaded in the first sentence and each following sentence carries facts (storage model, formats, size cap, prerequisite, removal). The 'Branding, not a fact' aside is slightly discursive, but it earns its place by explaining retroactive re-branding.

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 three-optional-parameter mutation with no output schema, the description covers inputs, storage semantics, constraints, prerequisite, and the resulting effect ('company logo stored (or removed)'). Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so per-parameter meaning is already documented, giving a baseline of 3. The description adds value the schema does not: the file-vs-URL choice is presented as mutually alternative input modes, and remove=true is framed as the inverse operation rather than just another flag.

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: 'Put your logo on the invoice document', then enumerates the two input routes (file upload, public https URL) and the removal path. It is unmistakably distinct from core_set_company_profile among the siblings.

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

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

It gives clear conditions for each mode: upload a file OR supply a public https URL, and 'Pass remove=true to take it off'. The prerequisite 'Needs a company profile first' is an explicit precondition. It stops short of naming a sibling alternative explicitly, which keeps it at 4 rather than 5.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-open-world mutation, so the description's main added value is the patch behavior and conditional first-time name requirement. It also states the effect explicitly as 'company profile written,' but does not cover permissions, validation failures, or whether changes are reversible.

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

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

The definition is compact and front-loaded: identity first, invoice dependency second, patch semantics third, and effect last. Every sentence contributes useful information without repetition or filler.

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

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

For a 13-parameter mutation with full schema descriptions and mutation/safety annotations, the description covers the essential context: what the profile is, its invoice dependency, and partial-update behavior. It is slightly incomplete around permissions, error behavior, and how this relates to sibling profile/logo/setup tools.

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 parameter descriptions already carry most semantics. The tool description still adds useful meaning beyond the schema by explaining patch semantics for all fields and that name is required only on first setup.

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

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

The description clearly identifies the resource as the business's own company profile and lists the identity areas it controls: seller block, tax id, payment instructions, country, currencies, tax scheme, and numbering. It does not explicitly state a verb like set/update in the first sentence and does not directly distinguish itself from the sibling read tool core_company_profile, so it falls short of a 5.

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

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

It gives useful invocation context: one profile per workspace, patch semantics, and that name is required only the first time. However, it does not explicitly say when to use this tool versus core_company_profile or related setup tools, nor does it provide exclusions or alternatives.

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

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

Beyond annotations, it discloses the effect on future confirmations, that lowering a limit does not affect already-confirmed orders, and that a limit of 0 means prepay only. It also establishes the audit expectation around the reason field. This is strong behavioral context for a non-read-only, non-destructive mutation.

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

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

The core purpose is front-loaded, followed by the decision context and the most important edge cases. The narrative style is purposeful here and does not waste 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 three-parameter mutation with full schema coverage and annotations covering safety flags, the description supplies the missing operational context: when to use it, what changes, what does not change, and the meaning of special values.

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 meaningful semantics not present in the schema: a limit of 0 means prepay only, and lowering a limit tightens the gate for future orders without touching confirmed ones.

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

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

The description states a specific action and resource: changing the unpaid exposure/credit limit carried for a customer. It also explains the operational context, making clear this is the human override to the credit gate rather than a general customer update.

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

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

It explicitly says when to use it: when o2c refuses to confirm an order, someone with authority should change the number here rather than route around the gate. It also gives the key exclusion, and the reason requirement is framed as part of the correct usage.

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

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

Annotations only say this is a non-readonly, non-destructive, non-idempotent write; the description goes far beyond that by disclosing the temporal blast radius, that historical documents are immutable, and that each change is logged as a record. This is exactly the kind of consequence disclosure a mutation 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 with the action and effect scope, and the trailing 'Effects:' line is a useful summary. Slightly repetitive — the 'future documents' idea is stated twice — but nothing is wasted.

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

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

For a two-parameter mutation with annotations and full schema coverage, the description covers the key behavioral consequence (immutability of already-raised documents) and the audit nature of the act. It does not mention permissions or what the call returns, but no output schema exists and those are minor omissions.

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 item_id and the cents-based unit_price, so the description adds no parameter-level meaning. Baseline 3 is appropriate when the schema does the work.

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

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

States a specific verb and resource ('Change an item's list price') and immediately qualifies the scope (future documents only). It is clearly distinct from core_create_item or inventory cost tools, though it never names a sibling to route against.

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

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

Gives clear context for when the change applies: documents raised from now on, with quotes already accepted and issued invoices unaffected (INV-19). It explains the rationale ('logged act and not a field edit') but offers no explicit exclusions or named alternatives for adjacent operations.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description goes further by disclosing return semantics not in any schema — the ordered missing-item list and the 'ask' field for what is still missing — plus the substantive rule that tax must be explicitly answered and the default is not an answer. It stops short of describing pagination/format or edge cases like a fully complete space.

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 readiness question is front-loaded and the content is ordered to match the workflow (what to write first, then what to ask, then scope exclusion). It is somewhat long and rhetorical in places ("the fastest way to lose them", "the default is not an answer"), but those lines carry actionable rules 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 zero parameters, no output schema and full annotation coverage, the description supplies the missing behavioral and procedural context: what the checklist contains, in what order, and how to act on each answer. Only the concrete shape of the response beyond the 'ask' field is left implicit, which is minor for a read-only status 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly spends no words on parameter behavior and focuses entirely on workflow.

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 states the exact question the tool answers ("Is this space ready to invoice, and if not, the next question to ask — in order") and enumerates the checklist contents: name, country, currency, tax scheme, address, payment instructions, numbering format, logo, first client. It also distinguishes itself from siblings by naming core_schema and core_set_company_profile as different concerns. An agent can identify this as the readiness-check tool without opening the schema.

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

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

It gives an explicit precedence rule ("Call this FIRST in a space you have not seen before"), a decision rule for the sibling mutation tool (write known facts to core_set_company_profile before asking anything), sequencing of questions, and a scoping exclusion ("Nothing here is needed for a job-hunt space"). This is about as close to when/when-not/alternatives as a description gets.

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, idempotent, closed-world safety, so the description's job is to add provenance — and it does: acts come from the implements map, evidence from the last conformance run, and results are 'derived, never asserted'. The note that refusals are included in the returned steps is a genuinely useful disclosure an agent could not get from the annotations.

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

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

The load-bearing content is front-loaded in the first sentence, but the closing flourish "refusals are half the curriculum" and the repeated 'teach' framing are editorial padding rather than operational information. Trimming would not lose anything an agent needs in order to call the tool.

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

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

With no output schema and only one optional parameter, the description carries most of the burden, and it does describe the shape of what comes back (acts, scenarios with steps showing doctrine and arguments, invariants with exercising evidence). What is missing is any hint of size, pagination, or how an unknown area is handled.

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% — the single 'area' parameter is already documented as a spec area defaulting to o2c. The description never mentions the parameter, so it adds nothing beyond the schema; baseline 3 applies.

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

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

The first sentence names a specific verb-and-resource pair — implementation status against an area spec — and enumerates the three things returned (acts, scenarios with evidence, invariants). It is well short of the top mark because it never distinguishes itself from adjacent introspection siblings like core_setup_status or core_schema; an agent must infer that 'spec' means something different from 'setup'.

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 answer to 'how far along is the spec, and how do you know'" and "Use it to teach" give a loose situational frame, but neither states a precondition, an exclusion, nor an alternative tool to pick instead. Usage is implied by the framing rather than instructed.

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 safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower, yet the description adds real value: patch-only mutation, the fact that credit limit/hold are out of scope, and that issued documents keep their original bill-to block. 'Effects: customer record updated' is filler, and there's no mention of failure behavior for an unknown customer_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 field list, then patch semantics, then scope exclusions — a sensible ordering. The trailing 'Effects: customer record updated' restates the obvious and could be cut.

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

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

For a 5-param partial-update tool with an output-schema-free interface and safety covered by annotations, the description supplies the essential semantics (patch behavior, scope boundaries, side effect on documents). Missing only edge-case handling such as unknown customer ids or validation of terms values.

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 meaning beyond it by framing the parameters as 'the customer's own facts' with a deliberate do-not-guess rule for addresses. It doesn't add format details (e.g., terms enumeration) beyond what the schema already 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?

Specific verb plus resource plus the exact field set it mutates ('email, billing address, tax id, terms'). It also draws the boundary with the credit-limit and hold commands and with issued documents, so an agent can separate it from core_set_credit_limit / core_hold_customer without reading their schemas.

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

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

Explains the patch contract ('only the fields you pass change') and gives an operational rule ('ask, never guess an address'), and carves out fields that belong to other commands. It stops short of naming the alternative tools explicitly (core_set_credit_limit, core_hold_customer), leaving the agent to infer which command to reach for.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing scoping behavior: on a hosted demo the response is restricted to the caller's sandbox, and sandbox names act as keys so other visitors' names are never exposed.

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

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

Two sentences, zero waste. The core action and the session-context detail lead, and the sandbox caveat follows as a secondary clause rather than burying the main point.

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

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

With no parameters and no output schema, the description must carry the return-shape burden; it conveys that the response contains a workspace list plus the caller's current workspace, which is the essential shape. It stops short of describing any per-workspace fields, which is the only remaining gap for a tool of this simplicity.

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 and the schema is an empty closed object, so there is nothing for the description to disambiguate. The baseline of 4 applies.

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

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

States a specific verb and resource ("List the workspaces on this deployment") plus an extra distinguishing output dimension ("which one this session is in"). No sibling tool in the set performs this listing, so the agent can identify it unambiguously.

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

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

Usage is implied rather than stated: an agent infers this is the orientation/discovery call for workspace and session context, but the description never says when to call it versus siblings like core_setup_status or core_reset_workspace, nor any prerequisites.

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 mutation/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely new behavior: the resulting state is "account created in not_started." It does not address duplicate handling despite idempotentHint=false, which is the one behavioral trait left undisclosed.

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 action and the mandatory-field gate are front-loaded in the first two sentences, and the closing "Effects:" line is a compact, high-value signal. The parenthetical CRM-3 / CRM-12 references add slight noise for an agent that has no way to resolve them.

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

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

With 9 parameters and no output schema, the description covers the mutation's landing state but says nothing about what is returned (e.g. the new account id) or how duplicates are handled given idempotentHint=false. Those are the remaining gaps an agent would hit on first 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% and each of the 9 fields carries a substantive description, so the schema does the heavy lifting. The description only reinforces that why_them and source_url are mandatory and frames why_them as an argument for the campaign goal — marginal added meaning over the schema's own text.

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

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

"Add a researched account to the list" gives a specific verb (add) and resource (account) plus a scope qualifier (researched, curated list) that separates it from funnel-style capture tools. It stops short of naming a sibling (e.g. crm_add_contact vs crm_add_account), so the agent must infer from the tool names which one to pick.

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 admissibility test: why_them and source_url are mandatory, and "If you cannot say why them and what changed, it is not a target yet" is a real when-not-to-use rule. No alternative tools are named, so the agent gets a gate but not a routing decision.

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 it is a non-destructive, non-idempotent write; the description adds the important behavioral fact that a name without a source is 'refused, not warned about' — a hard validation failure an agent must anticipate. 'Effects: contact created as named or gap' also confirms the outcome. Duplicate handling and return shape are unstated, so not a 5.

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

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

Front-loaded with the two-shape model before the rules, and every sentence carries either a mode definition or a validation rule. The prose is stylized ('a finding worth recording') but does not pad length meaningfully for an 11-parameter tool.

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

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

Covers the conditional parameter contract, the refusal behavior, and the creation effect — sufficient for an 11-param mutation with no output schema. What is missing is how duplicates or existing contacts at the same account are handled, and what the tool returns on success.

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 cannot express: source becomes conditionally mandatory whenever name is present, and gap_note is mandatory only when name is absent. That conditional-requirement logic is the critical piece for correct invocation.

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 — 'Record a person at an account' — and immediately defines the only two valid shapes (named with source, or gap with gap_note). This is far more precise than the sibling crm_update_contact or crm_get_contact, and an agent can distinguish the create path without opening the schema.

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

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

Gives explicit conditions for each mode: named requires name + source, gap requires gap_note, and 'Guessing is the only real failure here' draws a clear line about what not to do. It does not name sibling tools (e.g., when to use crm_update_contact instead), which keeps it from 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?

The annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description only needs to add context. It contributes a short 'Effects: event recorded as planned, with its source' line and the useful behavioral fact that source will be read back by a human deciding whether to attend. It does not address what happens on duplicate events despite idempotentHint=false, nor on an unknown account_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?

The purpose is front-loaded correctly, but the body is roughly 250 words for a simple record-creation call, and the CRM-20 warning is restated three times with a narrative illustration ('Reading one off by position is how a first approach ends...') plus a closing aphorism ('An event nobody can trace is a diary entry, not a record'). The anti-invention rule earns its place; the second and third restatements of it do not.

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

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

No output schema exists, so the description should signal what happens on success, and 'Effects: event recorded as planned, with its source' does that at a minimal level. With 100% schema coverage and full annotations, the remaining gaps are error/duplicate behavior and whether an event id is returned, which are modest but real for a 10-parameter mutation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real guidance beyond the schema: the format contract for source ('a URL when you found it, or "told by <name> on <date>"'), the account_id-vs-contact_id decision rule, and the intent of the note field. The date provenance rule is also reinforced in prose rather than left to 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?

The opening sentence gives a specific verb and resource ('Put something that is going to happen on an account') plus concrete examples (workshop, call, deadline), which clearly signals a scheduled-future event rather than a past-tense activity log. It never names the adjacent siblings (crm_log_activity, crm_update_event, crm_attend_event), so the distinction stays implicit.

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

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

It gives explicit when-to-use rules for contact_id ('when the event is with, or run by, a specific person') versus account-only for a public workshop, and an explicit when-NOT-to-create rule: 'If the source does not pin the date, there is no event; tell your human what you found and where.' That is both an exclusion and a fallback action.

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 a non-read-only, non-destructive, non-idempotent mutation; the description adds the real constraint an agent needs — the only legitimate data source is the human's own statement — plus an explicit effect statement ('attendance recorded on the event'). It stops short of saying what happens on re-recording an already-set attendance or what the call returns, which matters given idempotentHint=false.

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

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

The core rule is front-loaded, but the four-value list is repeated three times ('not attending, attending, registered, or went' / 'skip, attending, registered, or went') and asides like the CRM-22 ticket reference and 'whether your human goes is theirs' add rhetorical bulk rather than decision-relevant 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 two-parameter mutation with full schema coverage and clear annotations, the description covers authorization source, timing rule, effect, and the alternative tool. The only gap is response/overwrite behavior, which is minor since no output schema exists and the effect is stated.

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 enum is documented, so the baseline would be 3. The description earns more by explaining the semantic weight of 'went' (only valid after the event date) and by framing the values as 'the verb that fits' found events — nuance the schema does not carry.

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 ('Record where you stand on an event') and enumerates the exact accepted states. It also carves out the boundary against crm_update_event, which handles the outcome rather than attendance, so an agent can tell the two apart without opening either schema.

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

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

Explicit when-to-use and when-not: 'ONLY ON YOUR HUMAN'S WORD... If they said it, record it; if they did not, ask,' which rules out inference from any other source. It also gives a temporal rule ('went is for after the date') and names the sibling to use instead for outcomes.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real value by disclosing the default window and that results are windowed ('planned_after_window says what even that hides'), signaling possible truncation. It does not cover ordering, volume, or what an empty result means.

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?

Compact and mostly front-loaded, but the phrasing is oblique in places ('planned_after_window says what even that hides') and references result field names the agent has not seen. Four sentences carry some redundancy in re-explaining the default window.

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

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

With no output schema, the description usefully sketches the return structure (a by-day plan plus an awaiting_outcome list) and the truncation signal, which is what an agent most needs for this read-only query. Missing only detail on ordering and how the follow-up settling flow completes.

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 from/to defaults and formats, status enum, and account_id. The description's mention of the default window largely restates the schema, adding no new constraint or interpretation, 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?

Describes the resource clearly: upcoming events by day plus planned events that passed with no outcome recorded. It distinguishes itself from the two sibling tools it hands off to (crm_attend_event, crm_update_event) and reveals the shape of the result. The framing 'What is coming, by day' is a bit literary rather than a crisp verb+resource, but an agent can still tell what it returns.

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 read-order guidance ('awaiting_outcome is the list to read first'), a follow-up behavior ('Ask what came of it'), and names the two siblings that resolve the item. It stops short of contrasting with overlapping siblings such as crm_today, and states no when-not-to-use case.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: results are pre-aggregated rollups (accounts by status, gaps, staleness) rather than raw rows, plus a domain warning (CRM-13) that every why_them argues against adding accounts without reading the goal. It does not describe cost, size, or pagination, so it adds value without being rich.

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

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

Two sentences, front-loaded with the payload inventory and zero filler. The trailing '— the per-goal Today' clause is compressed to the point of being unclear, which costs it a point, but nothing is wasted.

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

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

With no parameters, no output schema, and safety already covered by annotations, the description gives enough to call the tool and to know what fields arrive. However, for a read-only survey tool in a crowded CRM namespace it should say how it relates to crm_today, crm_gaps, and crm_pipeline, which return overlapping information — that routing gap is the main missing piece.

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

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

Zero parameters and an empty schema, so there is nothing for the description to disambiguate; the baseline applies. The description correctly implies no filtering is possible on this call, since all scoping happens at the aggregate level.

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 the resource (every campaign) and enumerates what comes back — goal, status, health, accounts by status, open gaps, staleness — which separates it from the singular crm_get_campaign. The opening is a noun phrase rather than a verb, and 'the per-goal Today' is opaque jargon, but an agent can still tell this is the campaign-level rollup view.

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

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

The second sentence gives a workflow instruction ('read the goal before adding accounts to a campaign'), but that governs the downstream add-account action, not when to select this tool over siblings. It never names crm_get_campaign, crm_pipeline, crm_gaps, or crm_today, even though the returned fields ('open gaps', 'per-goal Today') overlap those tools directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is covered. The description adds genuine behavioral detail beyond that: the staleness definition ('no activity in 14 days') and the three content categories the result covers. It omits any indication of result size, ordering, or whether stale accounts are also counted in the status/tier breakdown.

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

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

One compact sentence with no filler, and the three output categories are front-loaded. The opening 'List health:' is slightly cryptic as a verb-resource pair, but nothing is wasted.

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

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

With no output schema, the description must convey the return shape, and it names the three categories but not their form (counts, grouped lists, per-account rows) or whether the campaign_id filter narrows all three. For a read-only overview tool with a 100%-documented single parameter, it is adequate but leaves the result structure ambiguous.

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

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

Schema coverage is 100% for the single campaign_id parameter, and the schema states it filters to an existing campaign id. The description never mentions campaign scoping, so it adds nothing beyond the schema. Baseline 3 applies when the schema carries the full parameter burden.

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

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

The description names a specific resource (a CRM health overview) and enumerates its three components: accounts by status/tier, open gaps, and stale accounts. An agent can tell it produces a composite health listing rather than a single-record read. It does not, however, distinguish itself from near-siblings like crm_gaps or crm_pipeline, which likely overlap on the 'open gaps' portion.

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

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

There is no explicit when-to-use, no exclusions, and no named alternative. The agent must infer that this is the dashboard/overview tool versus crm_gaps (gap listing), crm_pipeline, or crm_today from the sibling names alone. The 14-day staleness rule hints at a monitoring use case but is not framed as 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 readOnly=false, destructive=false, idempotent=false, openWorld=false, so the safety profile is covered. The description adds genuinely new behavior: the campaign is created 'as active,' and the goal becomes machine-read input that later account work must argue against. It stops short of saying what happens on duplicate names, which would complete the picture for a non-idempotent create.

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 action and the pre-check are front-loaded and the ordering is correct. Some rhetorical padding ('a folder, not a pursuit') and the inline ticket reference (CRM-13) cost tokens without adding operational guidance, but the core is tight.

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

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

No output schema exists, and the description covers the state effect (created as active) but not what identifier or object comes back, which an agent would want in order to chain into crm_add_account. Otherwise it is complete for a three-parameter, non-destructive create.

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 goes beyond it by explaining the consequence of `goal` — a research session reads it verbatim and every account's why_them must argue against it — which tells the agent how to write the value rather than just what field to fill.

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 (open/create) and resource (campaign) and immediately defines what a campaign is: 'a named goal that accounts will be pursued under.' That framing distinguishes it cleanly from crm_campaigns (listing) and crm_update_campaign (editing), so an agent can pick 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?

Explicitly tells the agent to check crm_campaigns first and to work under an existing goal if it covers the ask, plus a concrete protocol for deriving and confirming the goal with the human. This is exactly the when-to-use / when-not-to-use / alternative pattern.

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 declaring there is no outbound channel (CRM-14), that a refused list is checked against the written text at write time, and that the effect is an unsent draft recorded against the contact. What it does not disclose is the failure surface — what an invalid contact_id or a refused-list rejection returns, or whether a duplicate draft is blocked or merely discouraged.

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

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

Purpose is front-loaded in the first sentence and the rule blocks are scannable tags (CRM-14, CRM-10, CRM-16). Some redundancy creeps in — 'nothing is sent' is restated three times and the rationale requirement is duplicated in the schema — but on a high-stakes constrained tool most of the prose 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?

No output schema exists, but the description supplies what the agent actually needs: the effect of a successful call, the source material allowed for the body, the reviewer-facing purpose of rationale, and the eligibility rules for contact_id. An agent can call this correctly without further context.

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 prose adds real meaning the schema does not: rationale must name the hook or bullet the angle rests on and why this contact rather than another at the account, body carries no signature because it goes from someone else's mailbox, and contact_id must be a named live contact. The channel parameter is left entirely to the schema.

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

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

The first sentence names a specific verb and resource — write a message draft to a contact — and immediately bounds the scope with 'for a person to read, edit and send' and 'Nothing is sent.' It is clearly separable from crm_drafts (listing), crm_update_draft (editing), and crm_draft_outcome (recording an outcome).

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 preconditions and alternatives are spelled out: read the campaign's claims via crm_get_campaign first, use only record content, check crm_drafts before writing a second message to the same person, and restrict to named live contacts (not gap rows, not departed contacts). Nothing about when-to-use 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 flags (readOnly=false, destructive=false, idempotent=false), and the description adds the substantive side effects: the draft's text is copied to the activity trail, the draft becomes immutable, and the account status transitions to approaching. It also cites the governing rules (CRM-5, CRM-15), which is context an agent cannot get from structured fields.

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

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

Front-loaded with a one-line purpose, then cleanly segmented by SENT/DISCARDED blocks and closed with an 'Effects' summary. The cautionary paragraph about not fabricating a send is slightly discursive, but it is doing real work rather than padding.

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

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

The 'Effects' line substitutes well for a missing output schema, and the mutation consequences are fully spelled out. It does not address edge cases an agent may hit, such as what happens if the draft was already recorded sent/discarded (relevant given idempotentHint=false) or what error surfaces when sent_at is omitted on a send.

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 earns more: it clarifies sent_at means when the message actually went rather than when the record was typed (CRM-5), and it gives concrete guidance on rejected_because ('too long, and it opened on us rather than on them' is worth typing and 'no' is not). This is real semantic value beyond the schema's terse property 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 ('Record that a person sent a draft, or that they rejected it') and explicitly scopes itself apart from the sending action itself ('Sending happens in their mailbox; this records it'), which separates it from siblings like crm_draft_message and crm_update_draft. The two enum branches are named and defined inline.

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

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

Gives clear when-to-use conditions for each branch (SENT vs DISCARDED) plus an explicit when-not-to-use guard: 'Never record a send you were told about by nobody... If you did not hear it from your human, ask.' It also implicitly routes the actual send elsewhere rather than through this tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds context annotations cannot carry: this system has no send capability (CRM-14), so nothing in the list was sent by the tool, and status="sent" records what a person sent and reported back. That prevents an agent from mistaking 'sent' for an automated delivery and is exactly the kind of domain caveat that matters here.

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

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

The purpose and the actionable warning are front-loaded in the first two sentences, and every sentence afterward contributes a distinct semantic point. The CRM-14 parenthetical and the trailing clause about discarded reasons are slightly rambling, but no sentence is filler.

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

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

For a read-only filtered list with full schema coverage and no output schema, this covers purpose, call timing, and the meaning of the non-obvious enum values. Minor gaps remain — result ordering and what a returned record contains beyond contact/account are not described — but 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 mechanics of limit/status/account_id/contact_id are already documented, but the description adds real semantic depth to the status values beyond the schema's one-line 'Default draft' note — explaining what sent and discarded actually represent in this system. That meaning is not recoverable from the enum 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?

First sentence names the resource ('messages written but not sent') and its scope ('with the contact and account behind each'), so the agent immediately knows this is the read/list counterpart to crm_draft_message and crm_update_draft rather than a write tool. The follow-up sentence ties it to the drafting workflow, which further separates it from the create/update siblings.

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

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

'Check before writing a second one to somebody who already has one waiting' gives an explicit trigger for calling it ahead of crm_draft_message, and the note that discarded reasons are 'the most useful thing ... when you write the next one' reinforces the pre-drafting use case. It doesn't state when not to call it or name alternatives by tool name, keeping it 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds that results include each gap's note and age, and that only unresolved gaps are returned, but it does not describe ordering, pagination, or broader response behavior.

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

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

The first sentence is front-loaded and informative. The second sentence is philosophical framing about CRM-2 rather than invocation-relevant detail, so part of the description does not directly help an agent select or call the tool.

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

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

For a simple read-only list with one optional filter, full schema coverage, and rich annotations, the description provides enough context: it states that it returns unresolved gaps with note and age. No output schema exists, but the description sufficiently indicates the returned content for this simple 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?

There is one optional campaign_id parameter with 100% schema description coverage. The description does not mention the campaign filter at all, but with full schema coverage the baseline score of 3 is appropriate.

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

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

The description clearly identifies the resource as unresolved gaps and describes the output as a worklist containing each gap's note and age. It is specific about contents and scope, but it does not explicitly differentiate this from sibling tools such as crm_resolve_gap or crm_coverage.

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 worklist framing implies the tool is for reviewing unresolved gaps that need attention, but it does not explicitly state when to use this versus crm_resolve_gap, crm_coverage, or other CRM views. Usage is inferable but not guided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. With no output schema, the description carries the return-shape burden and does disclose the sections returned (narrative with provenance sources, path-in plan, contacts including gaps, recent activity, suggested next actions), which is genuinely useful beyond the annotations. It does not address behavior for an unknown account id or payload size, keeping it below 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?

A single compact sentence with the key qualifier ('Full account') front-loaded, so an agent gets the gist immediately. The keyword-list style is dense and slightly telegraphic ('path-in plan', 'what can be done next'), but nothing is padded or redundant.

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

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

For a single-parameter read tool with no output schema, the description adequately enumerates the returned facets and the annotations cover safety. The main gap is that it omits failure/empty behavior and leaves undefined domain terms ('path-in plan', 'gaps') to inference.

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

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

Only one parameter and schema coverage is 100% ('The account. An existing account id.'), so the schema already does the work. The description adds no further meaning about the identifier's format, source, or resolution rules — baseline 3 applies.

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

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

The description enumerates what a 'full account' contains (narrative with sources, path-in plan, contacts, activity, next actions), which implies retrieval, but never states a verb such as 'retrieve' or 'returns'. It is distinguishable from crm_update_account by the read-like framing, but nothing explicitly differentiates it from siblings like crm_coverage, crm_gaps, or crm_get_contact.

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

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

There is no guidance on when to call this versus alternatives — crm_coverage, crm_gaps, crm_today, crm_list_contacts, or crm_get_contact all overlap with the payload facets listed here. Nor is there any stated prerequisite (e.g., that the account must already exist) beyond what the schema implies.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety behavior is fully covered structurally. The description adds only the payload hint (goal, status, health) and says nothing about missing-campaign errors or how 'health' is derived.

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?

A single economical fragment with the key scope word ('One') front-loaded and zero padding. It is arguably over-compressed rather than bloated, but nothing is wasted.

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

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

The tool is simple and richly annotated, and there is no output schema, so the description's mention of goal/status/health is the only return-value signal - which is thin. It lacks error behavior and any hint of what a campaign record contains beyond the three listed fields.

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?

One required parameter with 100% schema description coverage, so the schema already explains campaign_id as an existing campaign id. The description adds no format, source, or lookup guidance beyond that, which is the expected baseline when schema coverage is 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?

States a specific resource and scope: a single campaign, returning goal, status, and health. The singular 'One campaign' implicitly contrasts with the sibling list tool crm_campaigns, so an agent can distinguish them, though the contrast is never made explicit.

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

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

No statement of when to use this versus crm_campaigns (list), crm_update_campaign, or crm_set_campaign_status. The only signal is the singular phrasing plus the required campaign_id in the schema, so usage must be inferred.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered and the bar is lower. The description adds the one thing annotations cannot: what the response payload contains (identity, provenance, gap state, activity). It omits behavior on an unknown contact_id and any permission/scoping caveats.

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?

A single terse clause with no filler, but the compression is excessive: 'provenance' and 'gap state' are undefined jargon, and there is no front-loaded verb telling the agent what action is performed. Short at the cost of clarity rather than through economy.

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

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

No output schema exists, so the description does the right thing by sketching the return payload's four content areas, but it stops there. For a lookup tool it never states what happens when the contact is not found or how large the embedded 'activity' can be.

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

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

Single required contact_id parameter with 100% schema description coverage (the schema even gives an example, 'P-0001'), so the schema fully carries parameter meaning. The description adds nothing about the identifier's format or behavior for unknown IDs, which is the expected baseline when the schema is 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 description is a noun phrase enumerating contents ('identity, provenance, gap state, the activity') rather than a verb+resource statement like 'retrieve a single CRM contact'. An agent can infer it fetches one person's record, but the tool name is doing most of the work, and nothing distinguishes it from crm_list_contacts or hunt_get_contact.

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

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

No indication of when to call this versus crm_list_contacts (lookup by id vs browse) or rim_gaps/crm_coverage which also expose gap state. The agent must guess the selection rule from names alone.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context. It does disclose one useful behavioral fact — the result set includes gap/unresolved contacts as well as named ones — but says nothing about ordering, volume, or how departed contacts are treated by default.

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?

A single front-loaded sentence with no padding. Its compactness costs clarity — 'provenance' and 'human-entered network fields' carry no concrete meaning — but structurally it is efficient.

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

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

With no output schema and no annotations explaining the shape of results, the description must convey what the agent gets back. It gestures at this ('provenance', 'network fields') but leaves key domain terms and the gap-vs-named distinction unexplained, so an agent cannot fully predict the payload.

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 enum parameter is documented, so the schema does the heavy lifting. The description hints that the default returns all states ('named and gaps'), which is mildly useful, but it never mentions the 'departed' enum value or how the filter interacts with those three states.

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

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

It states the resource and scope ('Every contact across accounts') and signals that unresolved 'gap' contacts are included, which separates it from a single-record getter. However, there is no explicit verb and jargon like 'gaps', 'provenance' and 'human-entered network fields' is undefined, so an agent must infer that this is a read/list operation and guess what the returned fields mean.

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

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

No guidance on when to use this versus crm_get_contact, crm_gaps, crm_coverage, or crm_list_contacts-like siblings such as hunt_contacts. There is no mention of prerequisites or exclusions; the agent must infer usage from the name alone.

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 write, non-destructive, non-idempotent, closed-world, so the description needn't restate safety. It instead adds genuinely non-obvious context: occurred_at reflects reality rather than entry time ('staleness math depends on the truth') and the summary's interpretive latitude vs. its factual provenance rule (CRM-10). It stops short of warning that retries will duplicate the record despite idempotentHint=false.

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

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

The action and the critical occurred_at caveat are front-loaded, and every sentence carries substance. The trailing 'Effects: activity recorded.' is near-empty filler that adds nothing an agent doesn't already know from readOnlyHint=false.

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 write tool with no output schema, the description covers the highest-risk semantic (occurred_at) well but leaves medium/direction undefined and never states what a successful call returns or how duplicates behave. Adequate but with clear omissions an agent would hit in practice.

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 67% and the description meaningfully enriches two key parameters beyond their schema text: occurred_at's distinction from entry time, and what belongs in summary (free interpretation, sourced facts). medium and direction still carry empty schema descriptions and no mention in the prose, leaving two enum parameters to inference.

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: 'Record a touch: what happened, when it actually happened, with whom,' which tells an agent this creates an activity record. It does not distinguish itself from nearby siblings like crm_add_event, crm_attend_event, or crm_draft_outcome, so an agent cannot route confidently on purpose alone.

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

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

Usage is only implied by the action itself ('Record a touch'), with no explicit when/when-not guidance and no named alternative. Given the dense sibling set containing crm_add_event and crm_draft_outcome, the absence of routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is fully covered without the description. The description adds that results are weighted by stage probability and grouped by status/tier, giving some sense of the aggregation behavior. It says nothing about ordering, result size, or how weighting is computed, so the added value is modest.

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

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

Two tight sentences with the primary framing front-loaded and the filtering behavior second. "The weighted where-are-we view" is slightly colloquial but does real work in conveying intent rather than padding.

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

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

For a simple, zero-required-param, read-only reporting tool with full annotation coverage, the description conveys enough: what entities, what grouping, what the weighting means, and the default scope. With no output schema present, a brief note on the returned fields would be the only remaining gap.

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

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

Schema coverage is 100% and the single optional campaign_id is already documented as "Only this campaign." The description contributes the complementary fact that omitting it returns everything, which is mild added meaning. Baseline 3 is appropriate for a one-param tool where the schema does the heavy lifting.

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

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

The description states a specific resource and shape: accounts grouped by status and tier with stage probabilities, characterized as the weighted pipeline view. It is clearly a read-only aggregate report rather than a record fetch or mutation, which separates it from most crm_* siblings. It stops short of naming a specific sibling to contrast with (e.g. crm_gaps or crm_coverage).

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?

"Filter by campaign or see everything" implies two usage modes and makes the no-arg default explicit, which is useful. However, there is no guidance on when to reach for this instead of adjacent views like crm_coverage, crm_gaps, or crm_campaigns, and 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?

Adds significant context beyond annotations: it discloses the non-idempotent nature (at most once), the reconciliation risk of duplicates, the creation flow through core's API, and explicit effects ('core customer created; account.customer_id linked'). It does not contradict annotations.

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

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

The core purpose is front-loaded, but the description is verbose and uses metaphorical language ('a reconciliation problem wearing a convenience', 'where this area's job ends and order-to-cash begins') that could be trimmed without losing essential 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?

Given the complexity (a mutation that bridges two domains) and the lack of an output schema, the description covers when to use, key constraints, and effects. It could specify return values or error behavior, but the essential invocation details are 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 description coverage is 100%, so the schema fully documents all parameters. The description does not add any parameter-specific meaning beyond what the schema already provides.

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

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

States a specific verb and resource: 'Create the core customer from a won account'. It distinguishes from siblings by specifying the precondition 'Won accounts only' and the once-only constraint, which likely differentiates it from core_create_customer.

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 clear when-to-use context ('Won accounts only, at most once') and implicitly when not to use (non-won accounts or already promoted). However, it does not name alternative tools like core_create_customer for non-won scenarios.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the mutation profile is already covered. The description adds genuinely new context beyond that: the gap_note is preserved on the row and provenance requirements still apply. It does not state what happens if the gap row is already resolved or whether a duplicate contact results, which are the remaining unknowns.

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 outcome is front-loaded in the first clause, followed by the exclusivity rule and the provenance constraint. Three short sentences with no filler; the (CRM-2) reference is the only item that costs an agent anything without a payoff.

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 eight parameters, a mutation annotation set, and no output schema, the description covers the conceptual model (gap becomes named, gap_note retained) adequately. It leaves open edge behavior an agent would want before calling: what happens when the contact already exists, and what a failed resolution returns.

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 fields well, which sets the baseline at 3. The provenance framing in the description reinforces why source matters but adds no syntax, format, or constraint detail beyond what the schema states.

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

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

The description states a concrete verb and outcome — "Turn a gap into a named contact" — and adds an exclusivity claim ("The only way a gap becomes named") that separates it from generic contact tools like crm_add_contact. It stops short of naming that sibling explicitly, so the differentiation is inferred rather than handed over.

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 only way a gap becomes named" and the required gap row context imply this is only for pre-existing gap rows, and "the gap does not lower the bar" signals the provenance requirement. However, no alternative is named for the non-gap case and there are no explicit when-not conditions or prerequisites spelled out.

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

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

Annotations only say non-readonly, non-destructive, non-idempotent. The description adds real substance beyond that: concluded is terminal, accounts remain readable (CRM-6), and the effect is status moved plus reason retained. It stops short of stating reversibility of pause or permission requirements.

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

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

Front-loaded with the action verb, then the reason rule, then the terminal consequence. The parenthetical ticket references (CRM-7 extended, CRM-6) add mild noise but the core sentences earn their place.

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

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

For a 3-parameter mutation with no output schema, the description covers the required-reason rule, terminality, and the resulting state. An agent has enough to invoke it correctly, though it says nothing about the return shape or error behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds meaning by explaining why reason is required (a decision that gets asked about later) and tying status changes to the terminal consequence, giving semantic weight beyond the schema's terse 'Where it moves.'

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

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

States specific verbs and resource: 'Pause, resume or conclude a campaign', with 'status moved' as the effect. Clear what it does, but it never names the neighboring crm_update_campaign to disambiguate the two, so sibling differentiation is left implicit.

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

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

Gives concrete conditions: reason is mandatory for paused and concluded, concluded is terminal. It omits explicit guidance about when to use this instead of crm_update_campaign, but the state-machine framing makes the intended usage clear.

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

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

Adds real behavioral content beyond the annotations: the whole-set replacement semantics and the fact that the prior plan is preserved in the audit trail. That audit-trail note also usefully explains why idempotentHint is false, since repeated calls accumulate history. It does not cover permissions or the response shape.

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

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

Front-loads the core action and then explains the replacement rationale in two tight sentences. The trailing "Effects: path-in bullets replaced." restates what the second sentence already said, which is mild redundancy but not bloat.

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

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

For a two-parameter, non-destructive-flavored mutation with no output schema, the description covers the crucial ambiguity (does this append or overwrite?) and the data-retention question. Return values are unspecified, which is the main remaining gap but a minor one for a setter.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description earns more by clarifying that the bullets array is a complete replacement rather than an append — a semantic distinction the schema alone ("The plan, in order.") does not convey. It also implies ordering matters, matching the array's intent.

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

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

Uses a specific verb ("Replace") against a specific resource (the ordered "how we get in" plan for an account), which is unambiguous. It does not, however, name a sibling or state how it differs from adjacent CRM tools like crm_update_account or crm_add_account, so it stops short of a 5.

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

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

The description makes the usage model implicit but readable: this is the tool for defining the whole plan, not appending to it. It never states when to use it versus alternatives, nor any preconditions (e.g., account must already exist, which is only inferable from the schema's "An existing account id").

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?

While annotations confirm it is read-only and safe, the description adds crucial contextual behavior by defining the meaning of the lists: 'Gaps are research work; stale active accounts are follow-up work; recent activity is context.' This helps the agent interpret the data types accurately.

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

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

The definition is concise and structured like effective product copy. It immediately addresses the value proposition in the first sentence, followed by the core value and necessary internal definitions, ensuring zero wasted words.

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

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

Given the lack of an output schema, the description provides a complete high-level overview of the results, detailing exactly which three types of information the user will receive and what those categories represent in a functional sense.

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?

Since the tool has zero parameters and 100% schema coverage, the baseline score of 3 is appropriate. The description adds no information regarding input 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?

The tool clearly defines its purpose as providing a daily, prioritized summary ('The CRM work queue'). It specifies the three main categories of output: open gaps, accounts going stale, and recent activity, making its function distinct from transactional siblings.

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

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

The description explicitly answers 'when to use' by framing the tool's purpose around the question: 'what deserves attention today.' This establishes a clear use case for daily triage compared to more granular update tools.

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

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

The description provides critical behavioral guarantees beyond the structured fields, such as 'Only the fields you pass change' and 'Provenance survives updates (CRM-9).' It also details the functional logic of the 'park' state (reversible with park='', moves account out of worklists), which is crucial behavioral context for an updater tool.

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

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

The definition is highly discursive and dense. It sacrifices conciseness in favor of comprehensive detail and business context. While the structure is logical (goal -> constraints -> behavioral rules), the sheer volume of explanatory text makes it less immediately readable than a perfectly concise definition.

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

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

Given the tool's complexity—involving nuanced operational states (parking), historical constraints (provenance), and the difference between status and fact—the description is remarkably complete. It covers the most important edge cases and behavioral constraints an agent needs before making a call.

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?

While the schema coverage is 100% (setting a baseline), the description adds essential operational semantics that the schema lacks. Examples include explaining that 'park' is a 'fact about what happened,' why `why_them` cannot be blanked, and that '1' in `tier` means 'worth a hand-written approach.' This adds significant decision-making value to parameter interpretation.

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 purpose is clearly defined as correcting or deepening the account narrative. However, while it is clear what the tool does, the description relies heavily on specialized CRM terminology, which could be slightly clearer in distinguishing itself from a general 'customer' update tool, though its focus on 'account' provides a good distinction.

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

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

This definition provides excellent usage guidelines by setting strict boundaries: distinguishing between 'status moves' and 'parking,' and explaining the unique semantics of the 'park' field. It directly addresses common operational pitfalls for this type of tool, significantly aiding agent selection.

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

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

Annotations already establish that this is a non-read-only, non-open-world, non-idempotent update. The description adds meaningful behavior beyond that: goal cannot be blanked, claim lists are replaced whole, claims are human-only, agents are refused at write time by claims_refused, and the gate cannot catch overstatements of allowed claims.

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

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

The description is organized into paragraphs and front-loads some key rules, but it uses flowery language and external references such as 'CRM-9 in spirit' and 'CRM-17' that may not help an agent. The claim-gate explanation is valuable but lengthy relative to the core update operation.

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 mutation tool with no output schema, the description covers the critical goal and claims behavior but omits name and target_profile entirely. It also does not describe what happens to fields that are not passed, leaving important update semantics incomplete.

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 67%, and the description adds important meaning for goal and especially the claims_allowed/claims_refused fields, including human-only entry and whole-list replacement. It does not compensate for the empty schema descriptions of name and target_profile, so it falls short of full parameter coverage.

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 'Sharpen a campaign' is metaphorical, but the later 'Effects: campaign updated; claim lists replaced when passed' clarifies that this is a mutation tool. It does not clearly enumerate all updateable fields such as name and target_profile, nor does it distinguish this tool from siblings like crm_create_campaign or crm_set_campaign_status.

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 description gives useful constraints: the goal may be corrected but never blanked, and claim lists are human-only and should be read via crm_get_campaign before drafting. However, it does not explicitly say when to choose this tool over alternatives such as crm_set_campaign_status or crm_create_campaign.

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 non-destructive, non-readOnly, non-idempotent. The description goes beyond them with substantive policy: departures set status=departed and never delete the row (CRM-6), and provenance is correctable but never removable (CRM-9) — genuinely useful for an agent deciding whether a call is safe. It does not state whether omitted fields are left untouched, which matters given idempotentHint=false.

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

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

Front-loaded with purpose and effect, and every sentence carries a rule or a constraint; nothing is padding. The rule codes (CRM-6, CRM-9) are cited without definition and the telegraphic phrasing ('confidence firms up') costs a little readability.

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

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

There is no output schema, and 'Effects: contact updated' adequately covers the return. However, for a 13-parameter mutation tool the description never says whether the update is partial (omitted fields preserved) or a full replacement — a material omission given idempotentHint=false and the 'Correct or extend' framing.

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 77%, and the description still adds meaning for the highest-risk parameters: it explains the departed semantics, the correctable-but-not-removable rule for source, and reinforces the HUMAN-ONLY constraint on the three relationship-graph fields. Notes, title and confidence_note remain undocumented in both places, but the risky parameters are covered.

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