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

Annotations only declare openWorldHint=false, so the description carries nearly the full burden and does disclose the key state prerequisite (statement must be unlocked to draft) and that retries are made safe via idempotencyKey. It does not cover permissions or what happens to already-generated totals beyond implying regeneration is required.

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 does, then the workflow precondition, then the retry-safety note. Every sentence 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?

For a mutation tool with no output schema and thin annotations, the definition covers the state prerequisite, side effects (appears on statement and audit trail, requires regeneration/re-approval), and retry safety. Only the response shape and permission requirements are unaddressed.

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

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

Schema coverage is 100%, so every parameter is already documented, including the sign convention and the idempotency key. The description adds only the workflow context in which idempotencyKey matters, so baseline 3 is appropriate.

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

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

States a specific verb and resource with scope: a manual commission adjustment, positive or negative, on a rep's statement for a period. It does not explicitly contrast with the sibling remove_statement_adjustment, but the operation is unambiguous.

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

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

Gives an explicit conditional workflow: for the adjust-after-approval path, first call approve_statement with status 'draft', then adjust, regenerate, re-approve. It names the sibling tool and the ordering, so nothing is left to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds substantive context beyond them: approval LOCKS the statement and causes recalculations to skip that rep+period until reverted. That downstream side effect is exactly the kind of behavioral disclosure an agent needs and is not captured by annotations; only the reversibility/response shape is left implicit.

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 action and the lock warning front-loaded. The warning glyph calls attention to the destructive consequence without wasting 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?

No output schema exists, and the description covers the action, both modes, and the lock side effect; annotations carry the safety profile. It stops short of describing what the response returns or what happens to already-locked statements on repeat calls, which would fully close the loop for a state-changing tool.

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

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

Schema coverage is 100% and each parameter (including the status enum) is documented there, so the baseline is 3. The 'no approve: true shorthand' note adds useful API-convention clarity, but the stated body '{period, status}' omits repId, which is the required first parameter — slightly inconsistent with the actual payload.

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 ('Approve a rep's statement for a period') and immediately distinguishes the two modes (status='approved' vs status='draft' to unlock). An agent can tell exactly what this tool does and which operation it maps to without inspecting the schema.

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

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

Gives clear selection guidance between the two modes and their meaning ('approved' locks, 'draft' unlocks). It does not name sibling alternatives or note when this should not be used (e.g. before recalculation), but the when-to-use context is explicit enough to act on.

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 openWorldHint=false, so the description carries most of the burden. It usefully discloses the identity-vs-version ID pitfall and the required downstream recalc step, but says nothing about duplicate/overlapping assignment handling, whether re-assigning mutates existing assignments, or permission requirements for a mutation 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?

Three short sentences, front-loaded with the action and immediately followed by the most likely failure cause (identity vs version ID) and the required workflow. No filler or restatement of the title.

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 thin annotations, the description covers the essential call-time decisions: correct ID type, source tools for both required IDs, and the follow-up steps needed for the assignment to take effect. Missing only failure/overlap semantics.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including planId, repIds, currency override and the effective date range. The description reinforces the planId identity constraint and the optional effective-date bounding but adds no syntax, defaults, or edge-case meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Assign one or more reps to a plan') with scope ('optionally bounded by effective dates'). It also disambiguates from the plan-version concept in the same sentence, so an agent can distinguish this from unassign_plan and from plan-creation siblings without opening a schema.

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

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

Gives explicit sequencing guidance — assign, then set_quota, then recalculate_commissions — which names two sibling tools and the order to invoke them. It also names list_plans as the source of planId. The only gap is no explicit statement of when not to use it (e.g. use unassign_plan/set_rep_overrides 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 only declare openWorldHint=false, so the description carries the behavioral load and does it well: it discloses that config validation is client-side, that simulate_plan is advisory and diverges from the live engine, and that simulation ignores per-rep tier overrides. It stops short of stating side effects like duplicate-name handling, required permissions, or what the create returns.

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

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

Front-loads the action, then prerequisites, then the cautionary note about simulation, then the follow-up sequence. Every clause carries routing information and there is no filler.

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

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

For a create tool with a nested free-form config object and no output schema, the description supplies the missing shape guidance via get_plan_schema and list_plan_templates. It omits only what happens on validation failure or what identifier is returned, which is minor given the constraints.

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

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

Schema coverage is already 100%, so baseline is 3; the description adds real meaning by telling the agent the config is validated against the canonical plan schema and pointing to get_plan_schema for its shape. The remaining parameters (currency, effectiveStart/End, fieldMapping) are left entirely to their schema descriptions.

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

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

States a specific verb+resource (create a commission plan, version 1) and implicitly distinguishes itself from update_plan by pinning the creation to version 1. An agent can tell exactly what it produces without opening the schema.

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

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

Explicitly routes to alternatives: get_plan_schema or list_plan_templates for the config shape, simulate_plan as a recommended pre-check, and a concrete post-create sequence (assign_plan, set_quota, recalculate_commissions). Covers when to use, what to do before, and what to do after.

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 destructiveHint=true, idempotentHint=true, and openWorldHint=false. The description adds valuable business impact: without a quota, the rep has 0% attainment and tiers will not fire until a correct quota is set.

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 two sentences, front-loaded with the action and ID requirement. The second sentence earns its place by explaining when to delete and the downstream attainment consequence.

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 destructive tool with full schema coverage and useful annotations, the description is nearly complete. It explains the action, source ID, intended use case, and business impact, though it does not mention confirmation behavior or handling of nonexistent quota IDs.

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

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

Schema description coverage is 100%, and the single quotaId parameter is already documented as coming from list_quotas. The description repeats that sourcing but adds no additional syntax or format details beyond the schema.

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

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

The description states a specific verb and resource: 'Delete a single quota row by ID'. It also identifies the source of the ID via list_quotas, making it easy to distinguish from list_quotas and set_quota.

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 conditions: remove wrong-period or duplicate quota rows. It also explains the consequence of deleting a quota and implies the need to set a correct quota afterward, but it does not explicitly name set_quota or state when not to use 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 establish read-only, idempotent, closed-world behavior, so the description only needs to add nuance. It does add one useful trait — that format applies only to single-rep exports and that JSON is the D10 payroll shape — but says nothing about export size, latency, or how period scoping affects the workspace-wide file.

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 dense sentence with the core action front-loaded and the two invocation modes following immediately. The parenthetical asides make it slightly cramped 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?

Covers repId and format well and needs no return-value explanation since there is no output schema. However, the period parameter — including what happens when it is omitted, given zero required parameters — is entirely absent from the description, which is a real gap for a payroll export.

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 earns above baseline by explaining the semantics of omitting repId (workspace-wide CSV) and the meaning of the json value (D10 payroll format). It notably never mentions the period parameter, leaving that to the schema.

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

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

States a specific verb and resource ('Export statements for payroll') and clarifies the output formats, which separates it from list_statements and generate_statements by implication. It never names a sibling explicitly, so an agent must infer the boundary from 'export' vs 'list'/'generate'.

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 invocation guidance: omit repId for a workspace-wide CSV, pass repId for a single rep's export, with format choices 'csv' or 'json'. It stops short of saying when to prefer this over list_statements or generate_statements, and offers 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?

Goes well beyond the openWorldHint/idempotentHint annotations by disclosing overwrite semantics: DRAFT statements are overwritten on regeneration, APPROVED statements are locked and skipped. What's missing is cost/latency or concurrency guidance for a bulk generation job, and whether the source events are snapshotted at call time.

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, then scoping, then the destructive-behavior caveat, then the workflow chain. Nothing 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 two-param generator with no output schema, the description covers action, scoping, mutation semantics, and downstream steps. It doesn't say what the call returns (counts, skipped APPROVED reps, period echoed), which would help an agent verify 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 both parameters (period format, repIds scoping) are already fully documented in the schema. The description's repIds sentence largely restates the schema, and adds no format or edge-case guidance for period beyond what's there.

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 — 'Generate (or refresh) statement snapshots from live commission events' — plus the scoping dimension (all reps vs. specific reps). This clearly separates it from list_statements and approve_statement in the sibling set.

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

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

Explicitly names the seam: 'Omit repIds for all reps, or scope to specific reps,' and then places the tool in a concrete sequence (generate → list → approve → export), telling the agent exactly where this call sits relative to named alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds real behavioral context the annotations cannot: results are paginated and ordered newest first, and engine runs carry outcome counters. It stops short of describing the record shape or page-size defaults, but that is minor given schema coverage.

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

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

Two sentences, front-loaded with what the tool returns and then the diagnostic entry point. The 'who changed what, when' gloss and the one-call recipe both earn their place; nothing is repeated from the schema 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 four-parameter, fully documented, read-only list tool with no output schema, the description covers resource scope, ordering, pagination and the primary diagnostic use case. An agent has everything needed to decide to call it, choose filters, and interpret direction of results.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by specifying a practical combination — actor 'orchestrator' plus dealId — that maps filters to a diagnostic question rather than just restating field names. It does not explain the actor/dealId interaction boundaries (e.g. whether dealId alone includes webhook arrivals), which the schema only hints at.

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

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

States a specific verb and resource ('Get the workspace admin action log') and pins down exactly what the log contains: who changed what, when, plus every engine run with outcome counters. That content scope distinguishes it from siblings like get_recalculation_status or get_commissions_dashboard without needing the schema.

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

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

Explicitly names the decision context — 'First stop when diagnosing a missing or unexpected commission' — and gives a concrete invocation recipe (actor 'orchestrator' + dealId) to answer a specific question in one call. This is when-to-use guidance with the alternative workflow built in.

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

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

Annotations already declare readOnlyHint, idempotentHint and closedWorld, so the safety profile is covered. The description adds behavior beyond that: dealId yields a calculation trace, and includePeriods changes the shape of the response by adding distinct periods. It doesn't say whether the results are paged, limited, or what aggregation the team overview returns.

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, each carrying a distinct piece of information, with the default behavior front-loaded. Nothing is repeated from the schema 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 four-optional-parameter read tool with no output schema, the description covers the meaningful modes and the one output-shaping flag. It stops short of describing what the team overview contains (totals, groupings) or how conflicting parameters are resolved, which an agent could still get wrong.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining how the parameters interact to select a view mode rather than just restating each field. It doesn't clarify precedence when repId and dealId are both supplied, nor how period intersects with dealId.

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 and states the scope modes: team-wide by default, single-rep with repId, per-deal calculation trace with dealId. It is clearly a read-only reporting tool, distinguishable from mutating siblings like recalculate_commissions. The generic opening 'Commission earnings overview' is a bit vague, but the following sentences sharpen 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?

It explicitly maps parameter combinations to outcomes ('No params = team overview', 'repId = single rep dashboard', 'dealId = per-deal breakdown'), which is exactly the routing an agent needs. What's missing is guidance on combining repId + dealId or repId + period, and no alternatives are named.

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

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

Annotations already establish readOnly, idempotent, and closed-world, so the bar is lower. The description adds real behavior beyond them: identity IDs are silently resolved to the active version, and history/overrides are only fetched when explicitly requested — both affect what the caller receives.

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 with zero filler, front-loaded with the core operation and followed by ID resolution and the optional expansions. Every sentence carries information the agent needs.

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

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

With no output schema and only three simple params, the description covers the essentials: what is returned ('all rules and tiers'), ID resolution, and the optional expansions. Minor gaps remain around error/not-found behavior and payload size, but nothing that would cause a mis-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?

Schema coverage is 100%, so baseline is 3; the schema already documents planId, includeHistory, and includeOverrides. The description restates them and adds one meaningful nuance ('resolves to the active version'), but does not clarify what the active version means or what happens with an ambiguous/unknown ID.

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

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

The description gives a specific verb and resource ('Get a plan version with all rules and tiers') and states what the returned payload contains. It implicitly distinguishes itself from list_plans and get_plan_schema by returning a fully hydrated single plan version, but it never names those siblings to make the boundary 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?

The ID-resolution rule ('Accepts a planVersionId or a plan identity ID (resolves to the active version)') is genuinely useful usage context, and the two optional flags are framed as opt-in extras. However, there is no guidance on when to prefer this tool over list_plans for discovery or get_plan_schema for structure, so tool selection 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?

Adds the useful operational fact that there is "No network call," confirming the call is local/cheap, which reinforces the readOnlyHint/openWorldHint=false annotations with concrete behavior. It stops short of describing the schema's shape, versioning, or size, which would matter for an agent about to parse the result.

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, both load-bearing: the first defines the output and its consumers, the second the timing and the sibling alternative. Nothing is repeated from the title and no filler remains.

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 state that the result is a canonical JSON Schema for the config object, which is enough to act on. It could add a note on schema versioning or that the returned schema should be inspected before authoring, but nothing essential is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly spends no words on nonexistent inputs.

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

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

States a specific verb and resource ("Get the canonical JSON Schema for the plan config object") and ties it to the exact consumers (create_plan / update_plan / simulate_plan). An agent can distinguish this from list_plan_templates or get_plan without opening any schema.

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

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

Gives an explicit when-to-use ("before authoring a config from scratch") and an explicit alternative with its own condition ("use list_plan_templates for ready-made starting points"). The routing decision between the two tools is fully resolved in the description.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds important behavioral context beyond the annotations: status semantics, ~6h job expiry, loss on server restart, and what to do if the job ID is unknown.

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

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

Front-loads the core purpose, then efficiently covers status handling and fallback behavior. Every sentence carries actionable information with no redundant filler.

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

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

No output schema exists, but the description explains the meaningful fields and outcomes: result holds the synchronous summary on completion, error on failure. It also covers job lifetime limits and recovery alternatives, making it complete for an agent to call correctly.

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

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

Schema description coverage is 100%, so the sole jobId parameter is already documented as the ID returned by recalculate_commissions. The description reinforces the source of the ID and adds fallback guidance for unknown job IDs, but does not add format or syntax details beyond the schema.

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

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

States a specific verb and resource: checks the status of a background recalculation started by recalculate_commissions. This clearly distinguishes it from the sibling recalculate_commissions, which starts the job rather than checking 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?

Explicitly tells the agent when and how to use it: poll again on 'running', read result on 'completed', inspect error on 'failed'. It also gives a concrete fallback when the jobId is unknown, naming get_commissions_dashboard and get_audit_log instead of re-running the recalculation.

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 openWorldHint=false, so the safety profile is covered. The description adds behavioral context beyond that: success acts as a credential/URL validation signal. It stops short of describing failure modes or error responses.

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 filler, and the returned fields are front-loaded before the connection-check guidance. Every sentence 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?

There is no output schema, so the description carries the burden of saying what is returned — and it does so explicitly through the field enumeration. Combined with the annotations covering safety and idempotency, an agent has everything needed to call this correctly.

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

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

With zero parameters the baseline is 4; there is no parameter behavior to explain. The description correctly implies the tool takes no input by framing it as a simple check.

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 uses a specific verb and resource ("Get workspace info") and then enumerates exactly what comes back: name, connected CRM plus status, field mapping, subscription tier. This clearly distinguishes it from the plan/quota/statement siblings, which operate on different resources.

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 states a concrete usage role — "Use this as the connection check — if it succeeds, the API key and URL are valid" — which tells the agent exactly when to reach for it. It does not name when-not conditions or alternative tools, which keeps 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 and openWorldHint=false, so safety is covered. The description adds that results carry effective date ranges, but says nothing about what happens with no filters (full dump?), result ordering, or pagination/limits on a potentially large assignment list.

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 zero waste; the resource and returned data are front-loaded before the filtering options.

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 must carry return expectations, and it only gestures at 'effective date ranges' while omitting pagination, ordering, and unfiltered behavior. Adequate for a simple read tool, but with clear gaps.

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

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

Schema coverage is 100% and the schema documents both params; the description confirms they are alternative filters on rep and plan respectively. With zero required parameters, the baseline is 4, though it misses stating the default no-filter behavior.

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

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

States a specific verb and resource ('List rep-to-plan assignments') plus the returned field ('effective date ranges'), which separates it from list_plans or assign_plan. It does not explicitly name a sibling to route against, 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?

'Filter by repId or planId' implies how to narrow results, but there is no guidance on when to use this versus list_plans/get_plan, no mention of whether filters are combined or optional, and no exclusions. Usage is only implied.

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

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

Annotations already declare readOnly, idempotent and closed-world, so the description only needs to add context — and it does, by disclosing that results are snapshots rather than live CRM reads and by stating the pagination cap of 500. It stops short of saying how stale a snapshot can be or what the default ordering is, which would matter for incremental syncing.

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

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

Three sentences, each with a distinct job — define the resource, enumerate filters and pagination, then route to the sibling. The identity of the resource is front-loaded before any parameter detail.

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

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

For a zero-required-parameter list tool with full schema coverage and safety annotations, the description covers what is needed to call it correctly. The only remaining gap is the shape of a returned deal snapshot (which fields, what ordering), which the description gestures at but does not specify and which no output schema supplies.

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

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

Schema description coverage is 100%, so all five parameters already carry their own documentation including the ISO-date format, the 'normalized' stage values and the limit bounds. The description restates the same filters without adding syntax, accepted values, or interaction rules (e.g. how since combines with repId), so it is at the baseline.

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

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

The description pairs the specific verb 'List' with the resource 'deal snapshots' and defines that resource inline as 'latest CRM state per deal', so the agent knows exactly what a returned record represents. The clause 'discover deals without querying the CRM directly' further separates it from CRM-facing siblings and from get_commissions_dashboard.

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 states the use case (deal discovery from cached snapshots) and explicitly routes to get_commissions_dashboard when a per-deal commission breakdown is needed, which is a concrete alternative-plus-condition. It does not state any exclusions relative to siblings like list_reps or list_plans, but for a filtered list tool the routing guidance is sufficient.

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 and closed-world, so safety is covered. The description adds the non-obvious behavioral fact that the same tool returns two different result shapes depending on whether slug is supplied, which is exactly the kind of mode-switching detail annotations cannot convey.

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

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

Three short sentences, front-loaded with the resource definition before the downstream slug usage. The slug-passing behavior is stated in the first part and then restated at the end, a small redundancy that keeps it just below maximally 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?

There is no output schema, and the description compensates by naming the returned attributes (slug, label, type) and the option-value return mode. With a single optional parameter and annotations covering the safety profile, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by making the optional-ness of slug meaningful – omitted means list all fields, supplied means fetch option values for a select/status field. The select/status restriction is reinforced rather than merely repeated.

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 CRM deal field attributes) and enumerates the shape of what comes back (slug, label, type). It is clearly distinguishable from siblings like list_deals or list_reps because it is about field metadata for plan configuration, not records themselves.

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 explains both usage modes: no slug to enumerate fields, and passing a slug to get option values for select/status fields. It also tells the agent where the slugs get consumed (measure, payoutBase, condition fields). It stops short of naming alternative tools or exclusions, so it is clear context rather than full routing guidance.

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

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

Annotations already establish this as a read-only, idempotent, closed-world operation. The description adds useful behavior beyond annotations: default one-row-per-identity behavior, active-version preference, compact return fields, and the large-size warning for includeConfigs.

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

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

The description is dense but well front-loaded: scope and row model first, return fields next, and get_plan/includeConfigs guidance last. Every sentence earns its place; there is no filler.

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

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

With no output schema, the description adequately explains the returned row shape and key identifiers. For a read-only list tool with three optional parameters, it gives enough context to call correctly and to know when to use get_plan instead.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a useful default-behavior detail not in the schema: rows are one per plan identity and prefer the active version, which clarifies the effect of allVersions; it also reiterates includeConfigs' large payload tradeoff.

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 commission plans in the workspace') and clarifies the row model ('one row per plan identity; active version preferred'). It also distinguishes itself from get_plan by pointing there for full plan configuration.

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 directs agents to get_plan for a plan's full config and explains includeConfigs for inline configs. Usage is clear, though it does not spell out when to prefer this list over sibling list tools such as list_plan_templates.

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 readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is clear. The description adds useful behavioral context by saying templates are ready-made `config` objects for create_plan and that templateId returns a single template's full config.

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 three compact sentences, front-loads what is listed, and then explains the two usage modes. Every sentence adds useful information without repetition.

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

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

With no output schema, the description carries most of the return-value burden. It says the tool lists templates and that templateId returns a single template's full config, which is enough for an agent to call it correctly, though it does not describe the catalog item shape or ordering.

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

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

Schema description coverage is 100%, and the schema already documents that templateId is an optional slug and that omitting it returns the catalog. The description largely repeats this, adding only the phrase "full config" for the single-template case, so the schema remains the primary source of parameter semantics.

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

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

The description states a specific verb and resource ("List CompCode's canonical plan template starters") and enumerates the template categories. It also clearly distinguishes catalog listing from fetching a single template via templateId.

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 explains the main usage pattern: omit templateId for the catalog, pass templateId to fetch one template's full config, and notes templates are ready-made config objects for create_plan. It does not explicitly exclude or compare against alternatives such as list_plans or get_plan_schema, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is covered. The description adds 'the grid view' as a hint about result shape, but the period-format sentence describes a parameter that does not exist in the schema, which adds confusion rather than behavioral clarity.

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

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

Front-loaded and short, which is good, but the final sentence about period format does not earn its place because no period argument is accepted by the schema. Removing it would make the definition tighter and less misleading.

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 list tool with no output schema, the description should ideally say what the grid returns or whether results are paginated. Instead it spends its remaining space on an inapplicable period format rule, leaving the return shape underexplained.

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

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

Schema coverage is 100%, so both repId and planId are already documented; the description merely restates 'Filter by repId or planId'. The period-format detail has no corresponding parameter, so it contributes no usable parameter semantics.

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

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

Clear verb+resource: 'List quota targets', with a helpful parenthetical identifying it as the grid view. It does not explicitly contrast with siblings like list_assignments or set_quota, so an agent must infer the boundary, but the purpose itself is unambiguous.

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

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

It says you can 'Filter by repId or planId', which implies usage, but never states when to choose this tool over list_assignments or other list_* tools. No exclusions, prerequisites, or alternatives are given.

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

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

Annotations already establish readOnly, idempotent, closed-world, so the safety profile is covered. The description adds value beyond that by disclosing what each mode returns, including that repId mode yields extra fields (CRM provider, crmId, sync timestamps) not present in the list view. It doesn't mention pagination or result caps for the 'all reps' path, which is the remaining gap.

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

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

Three short sentences, each front-loading a distinct mode (all reps, repId, email) with zero filler. The most important behavioral warning is placed last for emphasis without 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?

There is no output schema, but the description compensates by enumerating returned fields for both list and detail modes, which is what an agent needs to interpret results. Minor gaps remain around multi-match behavior for email search and any limit on how many reps 'all' 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 coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining that repId unlocks additional detail fields and that email performs a search rather than an exact lookup, plus the strong 'search before assuming nonexistence' constraint that the schema only hints at.

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

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

States a specific verb and resource ('List all reps in the workspace') and enumerates the fields returned (role, active flag, manager, CRM linkage). It also distinguishes the three invocation modes (no param = all, repId = single detail, email = search), so an agent can tell exactly what each call shape does without opening the schema.

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

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

Gives explicit routing guidance for each parameter: repId for single-rep detail, email for search, omit for all. The directive 'ALWAYS search by email before assuming a rep doesn't exist' is a concrete precondition that steers agent behavior. It stops short of naming alternatives such as sync_reps_from_crm for refreshing rep data, so no explicit when-not-to-use.

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

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

Annotations already declare readOnly/idempotent/closed-world, so the bar is lower, yet the description still adds real context: statements are frozen snapshots and generate_statements is what mutates them, plus includeStatus triggers an extra status fetch. It does not describe the shape of the returned statement data.

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 behavior, then the two mode conditions, then the caveat and the related mutation tool. Three compact sentences with no filler.

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

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

Covers modes, the includeStatus dependency, and snapshot semantics, which is sufficient to call it correctly. With no output schema, a brief note on the returned statement fields would close the 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 schema already documents omit-for-team-view and requires-repId constraints, so the description mostly reinforces rather than adds. It does contribute the draft/approved value set for includeStatus, which the schema lacks.

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

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

States the verb and resource ('Get statement data') and immediately clarifies the two modes: team batch view without repId, single rep with it. It also distinguishes itself from the sibling generate_statements, which creates/refreshes snapshots. Slightly generic opening phrase keeps it from a 5.

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

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

Explicitly tells the agent when to omit repId (team view) versus supply it (single rep), and notes includeStatus is single-rep only. It also points to generate_statements for creating/refreshing statements rather than reading them, covering the main alternative.

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

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

Beyond the annotations, it discloses that commission events are rewritten, history is preserved in audit trail, approved statements are locked and skipped, and long-running scopes return { status: 'running', jobId } rather than failing. It also states a concrete rate limit, which is valuable operational context.

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

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

The description is dense but front-loaded and structured around the most important decisions: scope, destructiveness, locking, async behavior, and rate limit. Every sentence provides actionable 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 destructive, asynchronous recalculation tool with no output schema, the description covers all essential context: scoping rules, mutation behavior, statement locking, running-job response shape, retry guidance, and rate limits.

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

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

Although schema coverage is 100%, the description adds critical semantics not enforced by the schema: use exactly one of the three IDs, dealId is fastest, and omitting all IDs scopes to the whole workspace and is slow. This meaningfully improves 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?

The description states a specific verb and resource: 'Trigger a live recalculation of commission events.' It also clarifies scope options, making the tool easy to distinguish from siblings such as get_recalculation_status or generate_statements.

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

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

It explicitly says to scope with exactly one of dealId, repId, or planId, warns that no scope means whole workspace and is slow, and tells the agent to poll get_recalculation_status rather than retry when a background job is running. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true, but the description adds real substance beyond that: it is a hard delete, it is permanent, it touches a financial record, and only manual entries are in scope. It omits downstream effects (e.g., whether statement totals or recalculation status change) and that the idempotentHint means a repeat call is harmless.

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 destructive nature and scope limitation front-loaded. Nothing is repeated and every clause carries 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 three-parameter destructive delete with no output schema, the description covers what is removed, what is preserved, permanence, and the confirmation guard. It leaves open downstream effects on statement totals and any permission requirements, which keeps it from a 5.

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

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

Schema coverage is 100% and all three parameters are documented, so the baseline is 3. The description only restates the confirm: true requirement already fully spelled out in the schema, adding no format or lookup guidance beyond it.

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

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

The description gives a specific verb ("Hard-delete") and a specific resource ("a manual adjustment from a rep's statement"), then narrows scope by excluding engine-written commission events. An agent can distinguish this from add_statement_adjustment or delete_quota without opening any schema.

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

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

It states the clear condition for use — removing manual adjustments only, with engine-written events explicitly unaffected — which prevents the most likely misuse. It does not name a sibling tool as an alternative path or describe prerequisites (e.g., statement must not be approved), so it falls short of a 5.

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

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

Annotations already declare idempotentHint=true and openWorldHint=false, and the description's 'upsert' wording is consistent with that. It adds real behavioral context beyond annotations: the period-format coupling to attainmentPeriod and the fact that measure is resolved server-side by name to a plan rule.

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 front-loaded sentences with no filler: the upsert purpose comes first, then format constraints, then the measure/variableTarget semantics. Dense but each sentence carries information an agent needs.

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

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

For a 9-parameter mutation tool with no output schema, the description covers the trickiest semantics but omits what an agent would want: that period or periods is effectively required despite neither being in the required list, what happens to existing targets on upsert, and error behavior for unknown reps or mismatched periods.

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 does add value on a few params (measure name resolution, variableTarget's role when payoutBase='variable_target'), but it leaves the period/periods ambiguity and the quotaGroup/planRuleId interplay 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?

States a specific verb+resource ('Set (upsert) quota targets') and an explicit scope ('for one or more reps'), which clearly separates it from sibling mutators like delete_quota, set_rep_overrides, and read tools list_quotas/list_assignments.

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 constraints on how to use the tool: period must match the rule's attainmentPeriod with concrete format examples, and measure must use the rule NAME rather than an ID. It does not explicitly name a sibling alternative (e.g. set_rep_overrides vs this tool) or say when not to use it, keeping 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 flag destructiveHint and idempotentHint, so the description earns credit for adding what the annotations cannot: clearing reverts the rep to global rates, and simulation will not reflect the change. It does not state whether supplied rules replace or merge with existing overrides, which is the one meaningful behavioural gap for a destructive tool.

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

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

Three sentences, each doing distinct work: what the tool does, how to clear, where IDs come from, and the verification caveat. No preamble or restatement of the title.

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

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

For a destructive mutation with no output schema, it covers prerequisites, the clear path, and how to confirm the effect. It leaves open the replace-vs-merge question for the rules array, which matters for correctly invoking it twice.

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 sourcing guidance beyond the schema by saying ruleId/tierIndex come from get_plan and by restating that clear=true reverts the rep rather than merely deleting rows.

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 ('set per-rep tier rate overrides on a plan version') with an inline scope clarification ('same plan, different rates for one rep') that immediately separates it from the global plan-editing siblings like update_plan.

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

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

Gives the two operating modes (set overrides, or clear with clear=true), points to get_plan as the source of ruleId/tierIndex, and explicitly warns that simulate_plan ignores overrides and that verification should go through recalculate + dashboard — an alternative the agent would otherwise pick by default.

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

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

Goes well beyond the readOnly/idempotent annotations by stating nothing is persisted, that output may diverge from the live engine, and critically that per-rep tier overrides are IGNORED — a behavioral quirk no annotation or schema captures. The advisory caveat directly shapes how an agent should trust results.

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

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

Dense but front-loaded: the core action and non-persistence come first, then parameter modes, then the warning. Every sentence carries information, though the single-paragraph packing of two parameter modes plus a caveat is slightly heavy.

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 simulation with no output schema, an agent knows how to invoke it and how much to trust it. The only gap is that the description doesn't hint at the shape of the simulation result (e.g., per-rep or per-period breakdown), which matters for a tool whose point is inspecting output.

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

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

Schema coverage is 100%, so baseline is 3; the description adds genuine meaning the schema lacks, notably that period='all' buckets each deal by its own close-date period and that repId narrows to one rep. It also clarifies the planConfig/planId exclusivity that the flat schema leaves ambiguous.

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 ('Dry-run the commission engine') and scope ('against real workspace deals WITHOUT persisting'). Clearly distinguishes itself from siblings like recalculate_commissions and get_commissions_dashboard by framing the operation as a non-persisting simulation.

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

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

Explicitly says to pass either planConfig (pre-flight a new design) or planId (existing plan), giving the selection condition for each mode. It also gives a clear when-not-to-use clause ('not to certify exact payouts'), though it doesn't name a sibling alternative for exact payout figures.

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 context beyond annotations: the operation is an upsert that never deletes, and it is the only path by which reps enter CompCode. That supplants the need to infer deletion risk from idempotentHint alone. It does not say how soon the roster becomes visible to list_reps or what happens on rep-name conflicts, which keeps 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?

Two sentences, both load-bearing: the first defines the action and its destructive profile, the second defines the trigger and the alternative. Nothing is repeated from the annotations or the schema.

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

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

With no input params, no output schema, and only two annotation hints, the description covers the essentials: what is pulled, that nothing is deleted, and when to invoke it. Minor gaps remain around confirming whether the sync is synchronous and whether existing rep fields get overwritten on conflict.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly avoids inventing arguments such as a CRM id or rep filter.

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 ('Pull the latest rep roster from the connected CRM into the workspace') and immediately clarifies the write semantics with 'upsert — never deletes'. An agent can distinguish this from list_reps without opening any schema.

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

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

Gives an explicit trigger condition — 'Run when a rep is missing from list_reps' — and names the sibling to check first, plus the reason reps cannot be created another way. It lacks an explicit when-not clause (e.g. don't run if a sync already ran recently), but the selection rule is clear.

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

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

Annotations only say destructiveHint=true; the description adds the crucial non-obvious behavior that historical commission events survive and only future calculation stops, plus the follow-up path for reversing earned commissions. That is exactly the context an agent needs before invoking a destructive tool.

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

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

Three short sentences, front-loaded with the action, then the data-safety guarantee, then the follow-up alternative. Every sentence adds distinct 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?

Single-parameter tool with no output schema; the description covers what is deleted, what is not, and what to do next. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100% and the schema already says 'Assignment ID (from list_assignments)'; the description repeats that same provenance without adding format or validation detail. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb and resource ('Unlink a rep from a plan') plus the keying parameter, and is clearly distinct from its sibling assign_plan. An agent can distinguish it from list_assignments and recalculate_commissions without opening any schema.

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

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

Names the source of the ID (list_assignments) and routes the reverse-commission case to recalculate_commissions after unassigning. It does not explicitly state when not to unassign (e.g. mid-cycle implications), but the usage context is clear.

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

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

Discloses critical non-obvious behavior: config/date changes create a new append-only plan version with nothing lost, while status-only changes transition the version in place. It also warns that simulate_plan is advisory, can diverge from the live engine, and ignores per-rep tier overrides — information not present in the minimal 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?

Four sentences, front-loaded with the operation and scope, then versioning behavior, then a recommendation with caveat. Every sentence adds actionable information with no 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 mutation tool with minimal annotations and no output schema, the description covers the most important behavioral risks (version history, status transition, simulation caveats). It leaves minor gaps around permissions, error behavior, and the planRef identity-vs-version distinction, but is well above adequate.

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 only 50% schema description coverage, the description compensates by explaining which parameter groups trigger versioning versus in-place transitions. It covers config, dates, currency, and status conceptually, though it omits planRef semantics and only mentions active/archived even though the status enum also includes deleted.

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 (update) and resource (plan), then enumerates the mutable fields: config, effective dates, currency, and status. It also distinguishes the two mutation modes (config/date vs status-only), making the tool's scope immediately clear against siblings like create_plan or simulate_plan.

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

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

Explicitly recommends running simulate_plan on the config first to preview payouts, which gives the agent a clear preparatory step. It stops short of saying when not to use this tool or naming alternatives for status transitions, but the usage context is clear.

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