FinStat

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

Adds substantial behavior beyond the annotations: nothing is mutated, the call is model-backed and metered, takes three to five minutes, refuses books sealed under an older format, and findings vary between runs so absence of problems is not certified. The no-model-run and attach-to-running-audit semantics are exactly the kind of context 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?

Purpose, authentication rule and input routes are front-loaded, and the dense sentences each carry real information about determinism, output shape and retry behavior. It is long, and the enumeration of book package forms duplicates the schema description, costing some tightness.

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

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

An output schema exists, yet the description still usefully characterizes the return: a summary with exact controls inline, the full report behind a multi-read download handle, an analysed_book_handle, and the reviewed/needs_information/incomplete status values. Nothing an agent needs to call or interpret this correctly is missing.

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

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

Schema description coverage is 100%, so handle, book and workspace_tag are already documented, including the upload:N/download:N form and the size rationale. The description mostly restates the accepted book shapes and adds only the resealing constraint, so the 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 (audits one Standard Books document) and defines what a book comprises: chart, journal, registers, parties and recorded documents. That scoping distinguishes it from siblings like compare_standard_books, report_standard_book and verify_standard_document without needing to name 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?

Explains the two input routes (handle as the usual path for large books, inline book for small ones) and gives concrete operational guidance: a book already audited is answered with no model run, a call during a running audit attaches to that run, and timeouts should be retried with the same book. It does not explicitly compare against the closest audit/report siblings, which keeps it below 5.

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

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

Goes well beyond the readOnly/idempotent annotations: short-lived nonce, opaque check_id, the probe never being admitted, not metered, and the crucial rule that a transfer-service failure reports data_channel_unavailable rather than incapable. That last point prevents a serious misread of 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?

Front-loaded with the purpose, then the call protocol, then the status/error semantics. Dense but every sentence carries information an agent needs to interpret a verdict correctly.

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

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

Output schema covers return shape, and the description supplies the state machine (pending/capable/incapable) plus the error carve-out. Nothing an agent needs in order to call or interpret it 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 oneOf branches are structural, but the description adds the semantic role of each mode (start vs. verdict read) and that idempotency_key replays return the same probe. It doesn't explain format bounds (8-128 chars), which the schema already handles.

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

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

Opens with a specific verb+resource: proving whether the host can execute FinStat's signed HTTPS upload program. The framing as a capability probe (temporary, never admitted) distinguishes it from sibling tools like create_upload_sessions, which do real transfers.

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 two-mode call contract: start with workspace_tag + idempotency_key, then call again with check_id to read the verdict. It also states that exact replay of the start is safe, so the agent knows how to poll without ambiguity.

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, and the description stays consistent while adding real behavioral context beyond them: 'Nothing is changed and no model runs' signals no side effects and no LLM cost, and it discloses the output split between inline counts/trial-balance diffs and a handle enumerating every differing record. It stops short of noting limits such as book size or performance.

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 and no sentence is pure filler, but the middle is a single long semicolon-chained sentence enumerating matching keys for entries, accounts, parties, registers, documents and trial balances, which is hard to parse. That rule set is genuinely needed, yet it would read far better as a list, and some detail could be trimmed.

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 high-complexity comparison tool with nested object inputs, five parameters and an output schema, the description covers input modes, grouping/matching semantics, order-insensitivity, and the shape of the return (inline counts plus a handle). With annotations carrying the safety profile and the output schema carrying return-value detail, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both the handle/inline exclusivity pairs and workspace_tag scoping are already documented in structured fields. The description restates the handle-or-inline choice in prose but adds no syntax, format, or constraint details beyond the schema; baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('compare two Standard Books documents') and pins the comparison basis precisely: semantic content rather than shared ids. The 'same_identity' vs 'same_content' framing makes the tool's role distinctive among siblings like report_standard_book or invert_standard_book, though no sibling is named directly.

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 selection between the two input modes ('Supply each book by transfer handle or inline (first_handle or first_book, second_handle or second_book)') and gives a concrete motivating case (an export versus a workspace book after submission). It does not state when to prefer this over alternative reporting/inspection tools, so no exclusions are offered.

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 the key behaviors: each call appends a new snapshot, none is ever altered or removed, and the sealed content is frozen at as_of. It also clarifies operational traits (durable mutation, no model, not metered) that the annotations cannot express, and its 'nothing destroyed' framing is consistent with destructiveHint=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-loads the core definition before the mechanics and every sentence carries information. There is mild redundancy between 'keeps it, never changed' and 'none is ever altered or removed', and the trailing 'Durable mutation; no model and not metered' is terse to the point of being cryptic.

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 mutation with an output schema, the description covers the mutation semantics, immutability guarantee, cutoff behavior, and downstream retrieval path. Return values are covered by the output schema, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the per-field descriptions already carry the basics; the description adds the interaction between chart_id and as_of (the chart whose books are sealed, cut off at as_of) and the default when as_of is absent. It does not add format or edge-case detail beyond that, so it sits just above 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?

States a specific verb (seals) and resource (a set of books through a date) with concrete scope: chart plus every current entry dated on or before as_of. It explicitly distinguishes itself from create_view_link (read/open) and list_book_snapshots (list), so the agent can place it without opening any schema.

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

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

Gives the trigger scenario (quarter close / official results), the exclusion (later corrections are not captured; take another snapshot), and the follow-up alternatives by name (create_view_link with snapshot_id, list_book_snapshots). Nothing is left to inference about when this is the right call.

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

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

Goes well beyond the annotations by disclosing single-use semantics, expiry, that 'bytes are never returned inline,' that exact idempotency_key replay returns identical sessions, and that 'reminting never mutates the artifact' - resolving the apparent tension between 'Creates' and readOnlyHint=true. It also states the tool is 'Not metered,' which no annotation conveys.

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

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

Front-loaded with the action and result, then a second paragraph of operational cautions. Dense but every sentence carries information; the nested parenthetical defining chart_id/declaration_id is the only slightly heavy passage.

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

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

An output schema exists, so the description needn't document the returned programs or hashes. Given that, it covers purpose, lifecycle (single-use, expiring), idempotent replay, integrity verification, and non-mutation - the main gaps are the undocumented workspace_tag and expires_in_seconds 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 0%, so the description has to compensate. It explains the items subjects well ('a retained handle, an admitted source_document_id, or an admitted chart_id or declaration_id') and the idempotency_key replay contract, but workspace_tag, client_item_id, and expires_in_seconds (default 3600, max 86400) are never mentioned anywhere.

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: 'Creates single-use, expiring download programs for one or more authorized immutable artifacts,' with a signed GET program per item. It doesn't explicitly name the sibling it differs from (create_view_link / create_upload_sessions), so an agent must infer the download-vs-upload-vs-view distinction from 'signed GET program' 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?

Gives clear operational guidance: 'Verify every download against the returned SHA-256' and 'A failed or consumed GET needs a new session - mint again rather than retrying the signed URL.' It also warns not to retry signed URLs, which prevents a common failure mode. It stops short of naming alternative tools for cases where a persistent or non-force-download link is needed.

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

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

Adds substantial behavior beyond the annotations: the export path is model-backed and metered, typically under a minute, judgment only writes account descriptions/instructions and kinds unplaced accounts, and never sets amounts, dates, accounts or links. It also discloses the self-proving step (book proved against the export's own tables, differences surfaced as errors with evidence) and that the result sits behind a multi-read download handle. The only residual tension is that a 'makes a document' tool carries readOnlyHint=true; the description frames it as derived output rather than mutation of existing records, so this reads as generation rather than a contradiction.

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

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

Front-loaded with the outcome and the two source modes, then details per mode — a sensible structure. It is long (four dense paragraphs) and repeats some schema facts such as currency being required with export_handle, but nearly every sentence carries decision-relevant information 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?

For a metered, model-backed generation tool with an output schema, the description covers what an agent needs: which source to supply, what gets refused, what the model does and does not decide, latency, and what the sealed result contains. Return-value detail is a bonus rather than a necessity given the output schema, and the pointer to report_handle closes the loop on follow-up retrieval.

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: currency is required because 'an export never states it', report files must be added inside the zip, and the two source parameters are exclusive. These restate and reinforce the schema rather than introduce new syntax, so it lands just above baseline.

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

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

States a specific verb and resource ('Makes one Standard Books document') and immediately defines the artifact as a whole set of books — chart, journal, registers, parties, recorded documents — which separates it from create_standard_chart and create_standard_statements. It also names the two mutually exclusive sources up front, so the agent knows exactly what the tool produces before 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?

Explicitly branches on source: export_handle for a QuickBooks Online export (with the requirement that report files go inside the zip and that a bare workbook or CSV is refused) versus chart_id for a workspace-held chart. It also routes the output onward — 'hand it to audit_standard_book, or keep it' — giving the agent the natural next step and the alternative consumer of the result.

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

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

Goes well beyond the annotations by disclosing the side-effect profile ("Nothing installs and no party is minted"), the normalization list of auto-fixed non-facts, the refusal contract with stable codes plus JSON path and remedy, the multi-read download handle, and "Not metered". One caveat: sealing and retaining bytes is a state-producing behavior alongside readOnlyHint=true, though "nothing installs" keeps it from being a true contradiction.

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

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

Front-loaded with the core action, but the body is a dense run-on block that chains normalization cases, refusal semantics, workflow, and claim semantics into long comma-spliced clauses. Most content earns its place, yet readability and scanability suffer noticeably.

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 tool with a nested oneOf input and an output schema, this covers the missing pieces: input format restrictions, normalization versus refusal boundary, handle lifecycle, and the follow-on workflow. The remaining gap is that it explains return contents the output schema already provides, while never naming the nearest structural siblings for disambiguation.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds meaning the schema does not: the document must be a canonical chart_of_accounts per guide_canonical_schema, and the normalization rules (codes as numbers, enum case, underscore field names) tell the caller the document may be loosely formatted rather than strictly. source_name is left undocumented but is optional and self-describing.

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: sealing one Standard Chart from canonical chart JSON, sealed exactly as written. It also carves out a boundary against siblings by stating "Nothing installs and no party is minted", which separates it from post_chart_accounts and update_standard_chart. The jargon-dense phrasing ("species chart", "retained UTF-8 handle") costs some immediate clarity, 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?

Gives explicit input constraints ("CSV, notes and Markdown are not accepted; write the chart JSON first") and an explicit next-step sequence: review the result, register the handle, then post_chart_accounts installs and checks, and update_standard_chart repairs residual exceptions. What it lacks is a direct comparison against create_standard_book or create_standard_declaration_chart, which are plausible confusable siblings.

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

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

Annotations say readOnlyHint=true and the description reconciles that precisely: authoring/sealing does not change the books, only post_chart_accounts does. It adds the validation contract (the exact parser register uses, including chart_mismatch on the document's 'chart' name), the clarification_needed recovery loop, and the cost signal 'model-backed and metered'. That is substantial behavior beyond 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?

Front-loads the verb, scope, and kind choices before the validation and clarification details. It is fairly dense and has some redundancy with the schema's own property text, but each paragraph carries a distinct idea (what it does, how it validates, what happens when ambiguous, what state changes) 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 7-parameter, nested-schema tool with an output schema, the description covers what an agent needs before calling: scope, kind selection, the two mutually exclusive input arms, validation failure modes, the ambiguity recovery path, and the fact that no books move. Return-value detail is correctly left to the output schema.

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

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

Schema coverage is 100% and the property descriptions already carry 'account codes are not needed', the description/document exclusivity, the chart-name-not-chart_id rule, and the model-call distinction. The description restates these, which is useful corroboration but adds little meaning beyond the schema; the only genuine addition is tying validation to register's parser, which is not per-parameter semantics. 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 — 'Authors one sealed declaration' — and pins its scope ('whose meaning belongs to exactly one chart, selected by chart_id'), which is exactly what separates it from create_standard_declaration_workspace. It also enumerates the three declaration kinds, so an agent knows both what it makes and which variants exist 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 clear when-to-use context: choose one of three declaration kinds, supply ordinary-language description, then review and register the result. It also explains the handoff — nothing changes the books until post_chart_accounts posts the chart — which routes the agent to the posting tool for the actual write. It never explicitly contrasts the two arms (description vs document) as a usage decision, or names the workspace-scoped sibling, 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?

Well beyond the annotations, it discloses cost/model behavior ('Model-backed and metered', the document arm performs 'no model call' with llm_called false), the failure mode for ambiguity (returns clarification_needed with one specific question and can be re-called), and lifecycle ('Nothing changes the books... returns the sealed document by value'). This reconciles the apparently contradictory create/readOnly combination: nothing persists until register/submit. Minor gap: it doesn't say what authorization or workspace state 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?

The core purpose and the enum choice are front-loaded, which is correct, but the prose is padded with ornamental phrasing ('true in shared workspace reality', 'accountable assertion') that costs tokens without adding precision. Some sentences are load-bearing (document arm, clarification_needed, metering), but the paragraph is denser than a 6-parameter tool with full schema coverage requires.

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

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

With an output schema present, return values needn't be explained, and the description still covers the hard parts: the two authoring arms and their exclusivity, the ambiguity/retry path, metering, the advisory filename, and the downstream register/submit step. What's left implicit is the relationship to sibling declaration tools and any preconditions on workspace_tag.

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 genuinely adds meaning: the canonical partyType value set (individual, business, trust, nonprofit, government, unknown), the constraint that parties carry only name/partyType/aliases, that one account_identity identifies one account, and that one parties declaration may assert a set with aliases. The mutual exclusivity of description vs document is reinforced in prose as well as 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 gives a specific verb and resource — 'Authors one sealed declaration' — scoped to a workspace, and explicitly contrasts the return shape with create_standard_chart ('this door returns the sealed document by value; create_standard_chart returns a handle'). The phrase 'true in shared workspace reality and names no chart' is opaque jargon, but the follow-up enumeration of the five declaration kinds makes the actual purpose 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 tells the agent which of the five declaration kinds to select and gives routing rules for the tricky cases: contacts and addresses must go in party_profiles rather than parties, and source_assessment should prefer 'its exact document arm with the original finding and a reason.' It also states the follow-on workflow (review, register, submit). It never states when NOT to use this tool versus create_standard_declaration_chart or open_standard_document, so it stops short of full 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?

The description says this tool retains a source, creates a durable FinStat Task, registers returned Standard Statements, persists taskId, and is metered when new interpretation runs. Those are side-effectful creation behaviors, but the annotations declare readOnlyHint=true and idempotentHint=true. The description therefore contradicts the read-only annotation and fails behavioral transparency despite otherwise rich operational detail.

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 purpose and follows a logical sequence from source selection to task handling and errors. It is dense and appropriate for a complex tool, though some operational details are repeated and the example adds length. It remains readable and mostly earns its space.

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

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

Given the nested schema, output schema, and complex task semantics, the description is complete enough for an agent to call the tool correctly. It covers source exclusivity, transfer-program flow, inline limits, statement shape, normalization and refusal behavior, task polling, expiring handles, exact-byte replay, and metering. Nothing essential about invocation is missing.

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

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

Schema coverage is 100%, so the schema already defines all six parameters in detail. The description still adds meaningful constraints beyond the schema: exactly one byte-bearing source must be supplied, file_name and mime_type may name it either way, and inline content_base64 is practically limited by MCP client argument caps. It also points to guide_canonical_schema for agent-built statement JSON.

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: retaining one exact financial source and creating its complete ordered set of Standard Statements as a durable FinStat Task. It also distinguishes the statement-creation role from helper flows like create_upload_sessions and submit. An agent can tell what this tool produces 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 source-path guidance: use the transfer program as the reliable intake, use inline content_base64 only for small sources, and switch to transfer rather than shrinking the source if an inline call fails. It also says to pass agent-built statements via the statement parameter. However, it does not explicitly compare this tool against sibling creation tools such as create_standard_book or create_standard_chart.

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 carries genuinely valuable behavior the annotations do not: exact replay of the idempotency_key returns identical sessions, changed inputs yield idempotency_conflict, size and optional SHA-256 are verified after PUT, bytes are retained unexamined, and the call is not metered. However, it opens with "Creates ... upload programs" while annotations declare readOnlyHint=true and destructiveHint=false — a mismatch an agent may act on when deciding whether a retry is safe. The "uploading admits nothing and authors nothing" clause partly reconciles this, but the verb/annotation tension should not be silently passed.

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, then the result shape ("signed PUT program per item"), then the idempotency contract, then the downstream consumer. Dense but every sentence adds distinct information; the only soft spot is that the read-only framing is buried mid-paragraph rather than stated up front.

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

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

An output schema exists and the description still usefully characterizes the return (a signed PUT program per item), and it covers expiry bounds, post-upload validation, and the downstream handoff. Gaps remain on authorization/workspace_tag semantics and on the read-only claim, which matter for a creation-style tool with a 50-item batch limit.

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 0%, so the description must compensate and it only partly does: it explains items as one-per-file, idempotency_key semantics (replay vs. idempotency_conflict), declared size / SHA-256 (max_bytes, sha256), and expiry (expires_in_seconds). It says nothing about workspace_tag, client_item_id, file_name, or media_type, leaving half the parameters undocumented in both schema and prose.

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: "Creates bounded, expiring upload programs for one or more files the host holds — one item per file." It also positions the result relative to sibling tools ("the handle feeds create_standard_statements or create_standard_book"), so an agent can distinguish this from the download-session and statement-authoring 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?

The description makes the usage flow explicit: this tool produces a handle that is then consumed by create_standard_statements or create_standard_book, and it notes the operation is "not metered." It stops short of naming exclusions or the sibling it replaces (e.g., create_download_sessions for the reverse direction), so there is clear context but no 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 cover readOnly/idempotent/non-destructive, but the description goes further with the access model (no credential, opens only for the workspace owner signed in to the console, grants nobody else access) and the live-vs-sealed distinction between workspace and snapshot views. 'Not metered' is extra operational context beyond the annotations; the 'Writes nothing. Read-only' clause is redundant repetition of readOnlyHint.

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

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

Front-loaded with the core action, then the modes, then the security caveat, then the safety tail. Dense but every clause carries information; the only waste is the 'Writes nothing. Read-only and not metered' tail, where the first half restates the annotation.

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

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

An output schema exists so return shape need not be explained, and the description still tells the agent the payload is a URL to hand to the user. For a three-parameter, read-only link generator the coverage of modes, provenance, and access semantics is 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 baseline is 3, but the description adds real meaning: it explains the mutual exclusivity as a mode choice and clarifies that passing workspace_tag alone yields the whole-workspace view. It also documents where each id comes from, reinforcing the schema's provenance hints.

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 ('Gives the user a link to see this workspace') and immediately enumerates the three scopes the link can take. It names the sibling tools that supply the ids (list_charts, list_book_snapshots), so an agent can place it precisely among the many create_* 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?

Explicitly tells the agent which parameter combination selects which view (workspace_tag alone vs chart_id vs snapshot_id) and what to do with the result ('Hand the url to the user to open'). It does not spell out a when-not-to-use case, but the mode-selection guidance is clear and actionable.

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

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

Goes well past the annotations: ownership transfer to the caller, billing attribution for metered work, the exact idempotency key (owner plus exact active name) with the workspace_reused return on retry, and the warning that workspace_tag must be persisted because the name is not a unique id. It also flags durability and that creation itself is unmetered, none of which the annotations convey.

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

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

Front-loaded with the action and scope, then idempotency, then next steps — a sensible ordering with no filler sentences. It is dense with domain jargon ('shared reality', 'admitted documents') that costs some readability but each sentence carries 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?

Covers ownership, billing, idempotency, the returned reuse signal, and the required follow-up sequence; an output schema exists so return-shape detail is unnecessary. An agent has everything needed to call this correctly and know what to do next.

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 semantic weight: it explains that name is the idempotency key for the principal, that actor is audit display only and is neither owner nor accounting party, and that description is stored and echoed. That reinforces and extends the schema's own notes.

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 and immediately scopes what the workspace contains (documents, charts, review work, reports). It also distinguishes itself from adjacent creation tools by declaring that creation asserts no accounting entity and admits nothing, which separates it from create_standard_declaration_workspace and create_standard_book.

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 downstream sequencing ('Next: gather source documents, create_standard_statements, then register, submit and post') and a retry rule. It does not explicitly name sibling alternatives such as list_workspaces or workspace_overview for read paths, so it stops short of a full when/when-not map.

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 real context beyond the annotations: it says the playbook drives downstream create/register/submit calls that are ordinary metered work drawn from the account's allowance, and it stresses that FinStat invents no evidence. However, 'Read-only and not metered' restates readOnlyHint and adds little, and it omits what happens to the scratch workspace afterward (cleanup, persistence, cost visibility).

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

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

The key fact — that this returns a prompt, not results — is front-loaded in the first clause, and the four sentences stay free of repetition. The 'FinStat invents no evidence; the agent does, visibly' line is somewhat rhetorical, but it carries real meaning about trust and provenance.

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 output schema is present and rich annotations apply, so the description does not need to explain return fields; it still conveys the pipeline shape, the metering consequence, and the demonstration's purpose. The remaining gap — the scratch workspace's lifecycle and how the agent should present results — is minor.

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 0 parameters, there is nothing for the description to disambiguate, so the baseline is 4; however, the description spends words on the downstream pipeline instead of the one thing an agent needs from a zero-arg tool — that it takes no input and returns a prompt rather than running the demo itself.

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 resource: it returns the demonstration playbook, and it spells out what that playbook instructs the agent to do (author a small synthetic bank statement, run it through the real pipeline in a scratch workspace: create, register, submit). That specificity separates it from generic guide tools, but it never names the nearby siblings (examples, get_started, guide_tasks) that an agent could plausibly confuse it with.

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

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

The intent — demonstrate FinStat without FinStat fabricating data — is implied clearly enough that an agent can infer when this tool is appropriate. However, there is no explicit 'use this instead of X' statement, no exclusion, and no guidance on when to reach for examples or guide_tasks 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 cover readOnly/idempotent/non-destructive/closed-world, and the description adds genuinely new facts beyond them: content is synthetic, it does not admit anything or touch a workspace, and it is not metered. Delivery behavior (stable link vs inline zip, small bundles only) is also disclosed.

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

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

The first paragraph is tight and front-loaded. The second paragraph, however, is about FinStat's document classification and routing to create_standard_book/create_standard_chart — useful context for the platform but not for invoking this tool, and it dilutes an otherwise clean two-parameter 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?

With an output schema present, the definition still covers the catalog-vs-fetch mode split, both delivery modes, and the nature of the content, so an agent can call it correctly on the first try. The trailing classification/routing material is out of scope for this tool and adds noise rather than needed 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% and the enum description for delivery already states 'url (default when available)... base64: the zip inline, small bundles only.' The description largely restates this, adding only the coupling of example_key omission to catalog mode, which the schema also documents. Baseline 3 is correct.

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

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

Opens with a specific verb and resource: 'Serves curated example bundles — each a small zip whose README is the runbook.' It also distinguishes itself from plausible siblings by defining the bundle as a runbook to follow with 'the ordinary public tools,' which separates it from demo/get_started/create_* tools.

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

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

Explicit operational guidance: no arguments returns the catalog, example_key fetches one, then unpack → create workspace → follow README. That is a clear when/how-to-use path. It stops short of stating when NOT to use it (e.g., vs. demo or get_started), so not a 5.

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

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

Annotations only cover the safety profile (readOnly, non-destructive, closed-world); the description adds substantial context on top: admission is neither required nor performed, workspace books are never read or changed, non-statement documents are rejected, the call is not metered, and the result is an expiring download handle with format, size and SHA-256. It also discloses polarity behavior and that original references are preserved separately from generated FITIDs.

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 paragraph structure separates format rules from side-effect/authorization behavior. Slightly verbose, with the format enumeration in prose partly duplicating the enum in the schema, but no sentence is wasted.

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

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

An output schema exists and the description still summarizes the meaningful return (expiring download handle, format, size, SHA-256). For a 7-parameter tool with conditional requirements, all the information an agent needs to invoke it correctly — authorization path, rejection case, billing, polarity — 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?

Schema coverage is already 100%, but the description still adds value by spelling out conditional requirements the schema encodes only structurally: bank_id for checking/savings, intu_bid additionally for QBO, fid as the separate OFX institution identifier, and that none of these are inferred from account numbers. This is above the baseline-3 case where the schema does all 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 — 'Converts one authenticated Standard Statement into one interchange file' — and immediately enumerates the closed format set. This is clearly distinguishable from siblings like render_standard_statement or create_download_sessions, which do not produce interchange files.

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 selection rules: OFX/QBO support checking, savings, and credit-card registers while 'other register kinds require CSV', and csv additionally requires a target. It stops short of naming an alternative sibling (e.g., render_standard_statement) and the condition that would select it, so routing versus siblings is inferred rather than stated.

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

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

Adds context beyond the annotations: amounts are summed as posted (no adjustments), the completeness field reports chart_exception, open requests, and notices, and the tool is not metered. 'Read-only' merely restates readOnlyHint, but the aggregation semantics and completeness semantics are genuinely new information.

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 front-loaded paragraph: the core action and scope come first, then parameter nuances, then behavioral notes. It is dense with semicolon-chained clauses and could be split for readability, but no sentence is filler.

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

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

An output schema exists, so return shapes needn't be spelled out, and the description still explains the notable completeness/ chart_exception field and the lack of metering. For a read-only, idempotent report generator this covers what an agent needs, though cross-tool routing guidance is absent.

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

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

Schema coverage is 100%, and the description largely restates the schema's own wording for chart_id conditionality, the inclusive YYYY-MM-DD cutoff, and the include_zero_accounts default. The baseline 3 applies because the schema already carries these semantics with no added nuance.

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 ('Generates a standard balance sheet') plus the exact scope ('for one chart as of one date') and the contents it returns (assets, liabilities, equity by account with totals, and the A = L + E verdict). This clearly distinguishes it from siblings like generate_trial_balance and generate_profit_and_loss.

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 conditional guidance: chart_id is needed only when the workspace has more than one active chart, and omitting as_of_date means all posted activity. It does not, however, say when to prefer this over generate_trial_balance or generate_profit_and_loss, so sibling 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavior: amounts are summed as posted, and the completeness field reports gaps (chart_exception, open requests, notices). 'Not metered' also adds cost/quota context absent from annotations, though 'Read-only' merely restates them.

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 statement type and contents come first, then input conditions, then result semantics. Nearly every clause carries information, though the trailing 'Read-only and not metered' half-duplicates the annotations and the run-on phrasing packs five distinct rules into one 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?

With an output schema present and full parameter documentation, the description need not explain return structures, and it still covers aggregation basis, chart disambiguation, open-ended dates, and the meaning of the completeness field. Minor gaps remain around accounting basis and whether comparative periods are included, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description largely mirrors the schema on chart_id, date bounds, and include_zero_accounts. It earns above baseline only through 'Amounts are summed as posted', which conveys the aggregation basis rather than restating parameter definitions.

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

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

States a specific verb and resource ('Generates a standard profit and loss statement for one chart') and defines the output contents (revenue and expense accounts, totals, net income), which implicitly separates it from generate_balance_sheet and generate_trial_balance. It never names those siblings, so routing still requires the agent to infer from accounting knowledge.

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 useful conditional guidance on inputs ('chart_id is required only when the workspace has more than one active chart', omitted bounds are open-ended), but says nothing about when to choose this statement over generate_balance_sheet, generate_trial_balance, or generate_report, and no exclusions are stated. Usage is implied rather than directed.

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 'not metered' and 'unfiltered/complete' beyond the readOnlyHint/idempotentHint annotations, telling the agent the payload is full-fidelity and safe to call repeatedly at no cost. It does not warn about payload size or latency for what is clearly a bulk dump, which is the only meaningful gap given annotations already carry the safety profile.

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 clause and the alternative-tool routing follows immediately. The enumerated list of six report_type values duplicates the schema enum and is the one clearly redundant sentence.

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

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

With an output schema present, the description needn't detail return values, and it supplies what the structured fields cannot: the audit-tier framing, the unfiltered scope, and the routing to human-facing alternatives. Nothing needed to select or 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 description coverage is 100% and each of the six constants already has a detailed description, so the schema does the heavy lifting. The description's 'closed six' enumeration largely restates the oneOf and adds only the framing that these are audit-tier views rather than user reports.

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 artifact: 'Generates one complete, unfiltered machine view of the workspace — the audit tier, as JSON.' It also states what the output enables (extracting the evidence chain behind the books), which separates it from every reporting sibling in the list.

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

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

Explicitly routes the agent away for human-shaped questions and names the exact alternatives by task: list_workspace_accounts/list_workspace_account_activity for accounts, list_chart_accounts for chart trees, and the three generate_* statements for financials. This is a clear when-to-use/when-not-to-use with named siblings.

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

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

Beyond the readOnlyHint annotation, it discloses that amounts are summed as posted, states the exact accounting-identity check, explains what the completeness field reports (chart_exception, open requests, notices), and notes the tool is not metered. These are genuine behavioral traits an agent cannot infer from 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?

A single dense paragraph that front-loads what the report contains, then parameter rules, then behavioral notes. Efficient with no filler, though the run of semicolon-clauses makes it slightly dense to scan.

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

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

An output schema exists, so return shape needn't be spelled out, yet the description still clarifies the verdict logic and the completeness field's semantics. For a read-only, four-parameter report tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema descriptions already state the conditional chart_id rule, the inclusive YYYY-MM-DD cutoff, and include_zero_accounts defaulting to true. The description restates these faithfully but adds little syntax or semantics beyond the schema, so 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 ('Generates a standard trial balance for one chart as of one date') and enumerates the payload (debit/credit balances, totals, difference, verdict). This clearly separates it from sibling report generators like generate_balance_sheet and generate_profit_and_loss.

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 conditional guidance for parameters (chart_id required only when multiple active charts; omitting as_of_date means all posted activity). It does not explicitly say when to prefer this over generate_balance_sheet or generate_report, but the 'as of one date / one chart' scoping implies the distinction.

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 adds genuinely new behavioral facts: it is 'not metered' and returns object_unavailable instead of a body for historical non-authorable kinds. It also flags the 'authorized' scoping constraint. Missing only latency/pagination-style details, which the output schema may cover.

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 return payload, then the selection rule, then edge-case behavior. Dense and purposeful, though the gloss on content_hash ('the document's own name: computed from its canonical content, identical wherever the document travels') is slightly verbose for the value it adds.

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 read tool with full schema coverage and an output schema, everything an agent needs is present: how to select the record, which identifier to prefer, what the body contains, and what happens for non-authorable kinds. Return-value detail is correctly delegated to the output schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond it: declaration_id is characterized as a workspace-local, stable id and content_hash as the document's own canonical name that is identical wherever the document travels. That portability framing is not in the schema's terse 'Portable content hash' text.

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

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

States a specific verb and resource with precise scope: returns one authorized declaration's canonical body plus its admission and application history. The singular 'one' plus the explicit body/history payload separates it from list_declarations without needing to name the sibling.

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

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

Gives a clear selection rule ('exactly one of declaration_id or content_hash') and explains the failure mode for historical kinds (object_unavailable). It does not explicitly state when to prefer this over list_declarations or open_standard_document, so it stops short of naming 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 readOnly, idempotent, non-destructive, closed-world, so the description clears the lower bar easily by adding real edge-case semantics: a missing profile yields an empty result rather than an error, while missing or foreign-workspace IDs produce a distinct 'party_not_found'. It also discloses that restricted-content references are withheld and that profile facts never post, which an agent could not infer from the annotations.

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

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

Four short sentences, front-loaded with the verb, resource and identifier provenance, followed by return contents and then failure modes. Dense but nearly every clause carries information; the closing 'Profile facts never change who a party is and never post' is slightly cryptic phrasing for what is really a no-side-effects guarantee.

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

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

With an output schema present, the description need not explain return shapes, and it correctly focuses on the things structured data cannot express: empty-vs-error semantics, the party_not_found case, and content withholding. Coverage is strong for a two-parameter read tool; only explicit guidance on when not to use it is absent.

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

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

Schema description coverage is 100%, and the schema already documents both the party_id and workspace_tag semantics. The description only repeats that party_id originates from list_parties, adding nothing about format or validation beyond the structured fields, 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 ('Looks up a workspace party by party_id') and enumerates what comes back: current non-posting profile, source assertions, hashes and conflicts. It also anchors the identifier to the sibling that produces it ('from list_parties'), so the agent can tell it apart from the list tool without opening a schema.

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

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

The 'by party_id (from list_parties)' phrasing establishes the natural call sequence: list first, then fetch details. It gives clear context for when this tool is the right one, but names no explicit exclusion or alternative for retrieving party data in bulk.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, and the description's "same every time / read-only / not metered" largely restates those. It does add genuinely useful behavioral context — transfer-session handles pass directly between tools with no re-upload, and workspace_tag makes steps callable rather than placeholder — but this describes the guide's contents more than the call's own 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?

For a zero-required-parameter, read-only guide fetch, roughly 170 words across three dense paragraphs is heavy, and much of it summarizes the guide's payload rather than helping select or invoke the tool. The lead sentence is well front-loaded, but the middle and closing material on statement types and file-format routing is only tangentially about this call.

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 schema is trivial, annotations cover the safety profile, and an output schema exists, so little is required; the description nonetheless conveys the workflow scope, the transfer-handle convention, and the optionality of charts. An agent can call this correctly and knows what class of content it receives.

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 single parameter is fully documented in the schema (100% coverage), so the baseline applies. The description does add one meaningful nuance the schema omits: an unauthorized or missing workspace_tag leaves host steps as host steps rather than producing placeholder calls, which tells the agent what happens on the failure path.

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 — "Returns the FinStat workflow" — and the rest of the paragraph enumerates the workflow's subject matter, so an agent knows exactly what comes back. However, it makes no attempt to distinguish itself from the many sibling guide tools (guide_tasks, guide_glossary, examples, demo), which is the main thing an agent needs when several tools look like entry points.

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 guide is the same every time" and "Read-only and not metered" imply it can be fetched freely and repeatedly, but there is no explicit when-to-call framing or statement of how it relates to guide_tasks or examples. The routing advice present ("A QuickBooks Online export zip goes to create_standard_book", "a trial balance ... is not a statement") guides the agent on downstream steps rather than on selecting 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 genuinely new behavior: it is non-blocking, 'wakes nothing', is safe to poll, is not metered, and — critically — that enqueued/processing are current-state counts rather than lifetime totals while completed counts finished effects. That counter semantics note prevents a real misreading of the output and is not in any structured field.

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 return contents, then the count semantics, then routing to alternatives — a sensible order with little waste. Minor redundancy in restating 'Read-only' when readOnlyHint already declares it, though 'not metered' is new information.

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

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

An output schema exists so return shape needn't be restated, yet the description still resolves the ambiguity an agent would hit — what each count means and whether polling is safe. For a single-parameter read tool with full annotation coverage, nothing needed 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 single workspace_tag parameter is fully documented in the schema as the active workspace id. The description adds nothing about the parameter, so the baseline 3 applies — the schema does all the work here.

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 ('Returns a non-blocking summary of the workspace's processing') and enumerates the payload: counts by public domain and state, unresolved failures, and inspectable public Tasks. It distinguishes itself from tasks_get and wait_for_workspace_idle by explicitly routing those use cases elsewhere.

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

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

Gives explicit alternatives with the conditions that select them: 'For one public Task use tasks_get or tasks/get; for a bounded workspace barrier use wait_for_workspace_idle.' It also tells the agent this is safe to poll, which is direct usage 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/idempotent/non-destructive/openWorld=false, and the description still adds real context: 'no workspace, and not metered,' plus what the payload contains (statement vs envelope_schema, authoring_notes for constraints JSON Schema cannot express). That is useful behavior beyond the annotation 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?

Purpose is front-loaded, but the body is a dense run-on with heavy jargon ('the shape the declaration tools' document arm seals') and drifts from the enum value 'declaration' to 'authorable declaration.' It is informative yet harder to parse than it needs to be.

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

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

With an output schema present, return values need not be spelled out, yet the description still explains the two statement payload shapes and authoring_notes. Coverage is strong; only the naming mismatch on 'declaration' leaves a small ambiguity.

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 params are enums, so the schema already carries most semantics; the description still adds the meaningful mapping from each species value to its consuming tool and flags 'statement' as the default. body_version is left to the schema, which is fine.

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

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

States a specific verb and resource ('Returns the exact machine schema for one canonical species') and then disambiguates all three species by naming the sibling each shape serves (create_standard_statements, create_standard_chart, the declaration tools). An agent can tell exactly what it gets 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?

Clear context for each mode: use 'statement' for the default statement shape, 'chart' for charts, 'declaration' for authorable declarations, plus 'topic csv' for CSV/bank-export construction. It does not say when NOT to use this versus guide_glossary or examples, so it stops short of explicit 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 already declare the tool read-only and idempotent. The description adds two operational facts the annotations lack: no workspace is required and calls are not metered. It also notes that a statement type key returns that type's form, which is non-obvious 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?

Four sentences, with the purpose front-loaded. Each sentence carries distinct information: purpose and scope, subset selection, the default, and the operational profile.

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

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

An output schema exists, so return values need no explanation. For a simple read-only lookup with two optional parameters, the description covers scope, parameter usage, prerequisites and cost.

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%. The description still adds meaning beyond it: statement type keys such as 'checking' or 'invoice' are valid terms and return forms. That clarifies what values terms accepts.

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 a specific verb and resource: it returns the FinStat glossary. It also lists what the vocabulary covers (documents, statements, declarations, charts, statement forms/types, the double-entry equation, interchange formats). That scope sets it apart from guide_canonical_schema and guide_tasks.

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 how to use the terms parameter: omit it for the full pack, or pass a statement type key to get that type's form. It never says when to call this tool instead of guide_canonical_schema, guide_tasks or get_started, so the reason to choose it has to 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the redundant "same every time" / "read-only" restatements add little. What does add value beyond the annotations is "no workspace" and "not metered" — operational facts an agent needs to know before spending a call that are nowhere in the structured metadata.

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 clause, and the trailing operational constraints (read-only, no workspace, not metered) are efficiently packed. The middle em-dash enumeration is dense and jargon-heavy (SEP-2663, io.modelcontextprotocol/tasks) and slightly obscures the core message, but no sentence is wasted.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description correctly focuses on what the guide covers and the dual-host model. It omits any mention of the detail parameter's effect, but that gap is fully absorbed by the schema, leaving little an agent needs that is missing.

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

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

Schema description coverage is 100% and the single enum parameter (detail: summary/full) is fully documented in the schema, so the description need not restate it. The description never mentions the summary-vs-full distinction or when to prefer full, so it adds no parameter-level 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 ("Returns the FinStat Task guide") and then enumerates the guide's contents: the MCP Tasks extension (io.modelcontextprotocol/tasks, SEP-2663), the ordinary-client parallel, and the shared submit / create_standard_statements workflow. It also distinguishes itself from the similarly named sibling tasks_get by noting the ordinary poll is FinStat's own and not part of the extension, so an agent won't confuse the two.

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 conditions the guide's applicability on host capability ("for hosts that advertise it" vs "hosts that do not"), which tells an agent which path applies to it. It does not, however, state an explicit trigger such as "call this before using submit" or differentiate from other onboarding siblings like get_started or demo, so exclusions are only partial.

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 genuinely non-structured context: it operates without a workspace, is not metered, and reports 'history.available' to indicate whether per-client request history is included — details an agent could not get from annotations alone.

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 useful facts, but the middle sentence about a 'paste-ready card citing the MCP specification' and the SEP-2663 citation is presentation detail that does not help tool selection, and return-value description is partly redundant given an output schema exists. Trimming that would sharpen it.

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

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

With an output schema present and zero parameters, the description need not document return shape, and the annotations cover the safety profile. What it adds — no workspace, no metering, history flag — is sufficient for an agent to call it correctly; only the missing sibling routing keeps it below 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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly spends no space on arguments and instead frames the call as argument-free introspection.

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 — it reports what the server observes about the current request — and enumerates the exact fields surfaced (client name/version, User-Agent, protocol revision, Tasks-extension advertisement, auth shape, transport). That is clearly distinct from diagnostic siblings like service_status (server health) or guide_tasks (documentation), so an agent can pick it without opening the schema.

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

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

The diagnostic intent is implied by 'what the server observes on this request' and the closing 'Read-only, no workspace, and not metered' tells the agent it is safe and cheap to call, but there is no explicit when-to-use framing and no named alternative (e.g., versus service_status) for related questions. 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?

It goes significantly beyond annotations by detailing critical failure modes like 'unresolved_entries' and 'withheld' documents, specifying the output status is 'needs_information,' and describing the reporting mechanism.

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 extremely dense and verbose. While every sentence contains crucial information, the sheer length and technical density make it unwieldy for quick agent parsing.

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 of the domain and the legal/technical nature of the process, the description is exhaustive, covering input, process flow, failure handling, and output structure.

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 description provides vital semantic context to the inputs—differentiating between a 'handle' and an 'inline book' object—which is crucial 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?

The description specifies a unique and complex transformation: turning a compiled Standard Books document back into its constituent parts (charts, statements, invoices, etc.).

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

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

It clearly defines input methods (handle or inline book) and provides strict operational constraints, such as only registering charts first and noting that nothing is registered or modeled in this process.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the bar is lower; the description still adds real value with the ordering guarantee ("oldest first") and the metering note ("not metered"), which annotations do not cover. It omits any pagination or result-size behavior, which is the main remaining gap for a list 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?

One front-loaded sentence with the verb first, no filler, and every clause carrying information (ordering, field list, cross-tool link, metering). Nothing could be removed without losing signal.

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

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

An output schema exists, so the field enumeration is partly redundant, but it usefully highlights snapshot_id as the handoff value for create_view_link. An agent has everything needed to call this correctly; only pagination/result limits 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 description coverage is 100% and the single workspace_tag parameter is already documented as the active workspace id returned by create_workspace and list_workspaces. The description adds no further parameter semantics, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Lists the workspace's book snapshots") with scope and ordering ("oldest first") plus the fields returned. An agent can immediately distinguish it from create_book_snapshot or list_charts without opening a schema.

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

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

The parenthetical "each one's snapshot_id (which create_view_link takes)" gives a concrete downstream reason to call this tool, effectively naming the follow-up tool. It stops short of explicit when-not guidance or naming list_events/list_review_items as alternatives, 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?

Annotations already cover readOnly/idempotent/non-destructive, but the description adds genuinely new behavior: the not-metered property and, importantly, that an unknown chart_id is an error instead of a silent widening. It also explains what 'total' means (signed sum of unvoided journal lines), which is useful behavioral context.

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

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

Front-loaded with the core action and scope, and every sentence carries information. The long enumeration of row fields is the weakest part, since an output schema exists and already conveys those names.

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 read tool with full schema coverage and an output schema, this is essentially complete: scope, error behavior, defaults, and cost profile are all covered. The row-field enumeration is redundant given the output schema, so it falls just short of full marks.

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 parameters already document defaults and the chart_not_found behavior, so the description largely restates the schema. It does clarify that chart_id may be active or retired only in the schema, not the description. Baseline 3 is right.

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 ('Lists chart accounts with their current balances') plus the scoping rule for chart_id. It does not explicitly distinguish itself from near-siblings such as list_charts or list_workspace_accounts, so an agent must infer the boundary from names 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?

Gives clear operating context: pass chart_id for one chart, omit it for every active chart, and an unknown chart_id yields chart_not_found rather than an empty or widened result. No explicit alternative tool is named for the 'I want flat accounts, not chart rows' 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=true and destructiveHint=false, and the description's 'Read-only and not metered' corroborates rather than contradicts them while adding the non-obvious metering detail. It also discloses meaningful behavioral context beyond annotations — chief among them that posting can be 'chart_exception' with a repairs path and that a sealed chart founds owner parties on new names.

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 bulk of the text is a dense run of field-by-field definitions (account_count, node_count, owner_disagreement_count, posting) that restate what the output schema already declares. Every sentence is informative, but several are redundant given the existing output schema.

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

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

For a single-parameter read tool with a full output schema and read-only annotations, the description is more than complete — it covers lifecycle, posting states, owner semantics, and the chart_id linkage to other tools. The only shortfall is that field-level explanations duplicate the output schema rather than adding new guidance.

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 a single parameter, workspace_tag, and schema coverage is 100% — the schema already explains it as the active workspace id returned by create_workspace/list_workspaces. The description adds 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?

Opens with a specific verb and resource: 'Lists the workspace's charts, active and retired alike,' and clarifies that lifecycle status distinguishes them. It never explicitly contrasts with siblings like list_chart_accounts or create_standard_chart, but the scope is unambiguous.

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

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

'Every row exposes chart_id, the selector the other chart tools take' implicitly tells the agent this is the entry point for chart workflows, and lifecycle/posting states hint at filtering. However, there is no explicit when-to-use vs. when-not guidance or named alternative for retrieving chart details.

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 'read-only' restatement in the description adds little. However, 'not metered' is genuinely new behavioral information (no quota/cost impact) and the note that results are summaries with full bodies elsewhere sets expectations about result weight.

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 is returned, followed by the get_declaration routing hint and the filter note. Every clause carries information; none is filler.

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

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

With an output schema present, return-value detail needn't be spelled out, and the description still summarizes the returned fields. It covers scope (admitted only), filtering, the alternative for full bodies, and cost behavior — enough for correct selection and invocation of a two-parameter read 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%, so both parameters are already documented, including the 8-value enum for kind. The description reinforces the enum by characterizing it as 'one of the eight authorable kinds' and framing the filter as optional narrowing, but adds no format or value-level detail beyond the schema; 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 ('Lists admitted Standard Declarations as summaries') and enumerates exactly which fields are returned (identity, scope, kind, attribution, admission time, application state with reason). It also distinguishes itself from get_declaration by noting that full bodies stay there, so an agent can separate 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?

Explicitly routes the agent to get_declaration when full bodies are needed, and explains that the optional kind filter narrows results to a single authorable kind. It gives clear positive usage context but no explicit 'when not to use this' beyond the get_declaration split, and doesn't distinguish itself from other list_* siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower; the description adds real value beyond them by disclosing that results are "not metered," that paging requires reading next_cursor "while more remain," and that each row carries member evidence plus each chart's latest judgment. It does not mention any auth/permission prerequisite or how retired events behave beyond the schema's default, 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?

Three sentences, front-loaded with purpose then filter surface then return shape; no filler. The middle sentence is dense and packs several concepts (five filter axes plus paging) into one clause, which is efficient but slightly crowded.

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

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

Given an output schema (so return-shape detail is optional) and rich annotations, the description still covers filters, pagination, and per-row content, leaving little ambiguity about how to call it. Minor gaps remain around what happens when no events match or whether pending evidence is excluded, but nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description largely restates what the schema already documents (kinds, filters, date window semantics, cursor paging). The one addition beyond the schema — the next_cursor read pattern — is also already implied by the cursor property's description, so no genuine lift over structured data.

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 ("Lists the events") and immediately qualifies the resource's provenance and subtypes ("derived from admitted evidence — movements, claims, and itemizations"). This is enough to distinguish it from siblings like list_review_items, list_chart_accounts, or list_workspace_account_activity 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?

Enumerates exactly what can be selected on (kind, endpoint account, owning party, reviewing chart, inclusive date window) plus pagination behavior, which gives an agent concrete selection criteria. It stops short of naming an alternative or a when-not case (e.g., use review items instead when you want unreviewed judgments), so it is not a full 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, but the description adds real behavioral contract: results are ordered by party_id, pages default to 100, next_cursor is always present and null on the final page, and the call is not metered. It stops short of covering error behavior or filter edge cases.

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

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

Front-loaded with purpose, then row shape, then pagination mechanics — a logical order with little filler. The row-field enumeration is somewhat long, and it partly duplicates the output schema, but it is dense rather than padded.

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

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

For a paginated list tool with full schema coverage and an output schema, the description covers what an agent needs: scope, ordering, page size, and the cursor contract. Minor gaps are the semantics of the name filter and error conditions on bad party_type 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 description coverage is 100%, so all five parameters are already documented, including the 1..200 limit bounds, cursor opacity, and the party_type enum. The description largely restates that (default 100, enum values, cursor round-trip) without adding new meaning about how the name filter matches.

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 ('Lists the workspace's parties') and defines what a party actually is — 'the people, businesses, and institutions its documents name' — which removes ambiguity an agent would otherwise have. It does not explicitly contrast itself with the sibling get_party_profile, 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?

Usage is only implied: enumerate parties in a workspace, page through with cursor. There is no explicit statement of when to prefer this over get_party_profile for a single party, nor any precondition or exclusion beyond 'read-only and not metered'.

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 substantial non-obvious behavior: the queue is re-derived from workspace state on every call, its length equals workspace_overview's open_review_items, requests sort and count ahead of notices, refs are stable identifiers, and acknowledgment 'changes no posting and does not repair the source'. The explicit clearing semantics per item kind are exactly the kind of context annotations cannot carry.

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

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

Purpose and ordering are front-loaded well, but the body is one dense block of run-on clauses, and the extended opening-reminder clearing predicate (chart binding, single-chart-account binding, pre-statement-period entry sums, currency rules) is heavy detail for a list call. Most sentences are load-bearing, but the lack of paragraphing makes a very long definition harder to scan than it needs to be.

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

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

An output schema exists, so return shape need not be described, and the description nonetheless covers derivation of the queue, ordering, stable refs, meaning of an empty result, and the full clearing path for every item kind. Nothing an agent needs in order to call this correctly and interpret the result 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?

There is a single parameter with 100% schema description coverage ('Active workspace id (the workspace_tag create_workspace and list_workspaces return)'), so the schema already does the work. The description contributes nothing about workspace_tag, so 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 ('Lists the findings that may need a human') and then enumerates the concrete categories of item. It explicitly carves out what is NOT a review item ('A chart_exception is not a review item... shows on list_charts'), which lets an agent separate this from list_charts and the chart tools without opening a schema.

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

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

Names the alternatives and the conditions that select them: attention items clear via resolve_review_items (dismiss), source reviews clear only through a submitted source_assessment acknowledgment, opening reminders only when a chart binds the account under stated conditions. It also warns that an empty result means no visible finding, not correct books, which directly shapes how an agent should follow up.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'read-only' is redundant, but the description adds genuinely new behavior: 'not metered', the bytes_available=false case for a portable Standard Statement admitted without its original, and the fact that chart/declaration rows hold the exact sealed register. That is meaningful disclosure of edge-case row semantics beyond 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 scope statement is front-loaded and the download routing is placed last, which is the right ordering. It is dense with domain jargon ('transfer tier's retained artifacts', 'sealed document register') and runs long, but nearly every sentence carries 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?

For a single-parameter read tool with a full output schema and complete annotations, the description covers scope, row contents, the key bytes_available caveat, and the download path. Nothing an agent needs to call or interpret it 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?

There is a single parameter and schema description coverage is 100%, with the schema itself explaining that workspace_tag is the id returned by create_workspace and list_workspaces. 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 ('Lists the documents admitted to a workspace') and immediately scopes it against a sibling concept ('not the transfer tier's retained artifacts'), which separates it from list_transfer_sessions. It also enumerates what a row contains, so an agent knows exactly 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?

Names the follow-on tool for the common next step ('Retained bytes download via create_download_sessions with source_document_id (or chart_id / declaration_id)'), which is real routing guidance. It also implicitly excludes the transfer-tier listing, but never states an explicit when-not-to-use condition or prerequisite beyond an active workspace.

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 genuinely new context: that the tool is not metered and that reconciliation verdicts are 'recorded, never gating,' which prevents an agent from wrongly treating violations as blockers.

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

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

Front-loaded with the core action, then enumerates summary fields and verdict semantics efficiently. The field enumeration is somewhat dense and overlaps with the output schema, but every clause is informative 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?

An output schema exists, so return values need not be explained, yet the description still enumerates summary fields such as semantic key, lineage, form, kind, verdict, and admission time. Combined with verdict semantics and the pointer to open_standard_document, an agent has everything needed to call and interpret the 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 the sole workspace_tag parameter is documented in the schema itself, referencing create_workspace and list_workspaces. The description adds no syntax or format details for the parameter, so the 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 ('Lists the typed statements admitted to a workspace') with an explicit scoping constraint. It is clearly distinguishable from siblings like list_source_documents, list_workspaces, and open_standard_document, which serve different resources or granularity.

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 open_standard_document as the route to full document content, giving an explicit alternative for a related need. It stops short of a true when-not-to-use statement (e.g., when to prefer list_review_items or verify_standard_document instead), so it falls just short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds genuinely new behavioral facts: 'not metered' (cost profile) and 'Rows are bounded summaries' (return fidelity), which tells the agent not to expect the full receipt. It does not cover cursor expiry or result-volume behavior, keeping it short of a 5.

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

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

Four compact sentences, each doing distinct work: identity, recovery use case, parameters, and result-fidelity plus sibling routing. Nothing is repeated from the title and no sentence could be dropped without losing information.

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

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

An output schema exists, so return values need not be spelled out, and the description still warns that rows are summaries rather than receipts. With the recovery scenario, sibling routing, paging, and metering all covered for a 4-parameter read tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is only 25% (only workspace_tag is documented), so the description has to carry weight, and it does: it names status as a filter and limit/cursor as the paging pair, and front-loads the newest-first ordering that governs cursor semantics. It stops short of explaining what each status value means or how long a cursor stays valid.

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 ('Lists this principal's durable submission Tasks'), plus scope ('in one workspace') and ordering ('newest first'). It also differentiates from the two nearest siblings, tasks_get (full receipt) and list_transfer_sessions (statement-creation Tasks), so an agent can pick correctly 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 names the triggering situation: 'the recovery path for a lost taskId after disconnect, timeout, or restart'. It also routes the exception case away to list_transfer_sessions and points to tasks_get for full detail, covering when-to-use, when-not, and 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds details not in the annotations: a hard cap of 50 results, newest-first ordering, and that calls are not metered. It does not describe behavior when more than 50 tickets exist (silent truncation) or failure modes.

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

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

One dense sentence that front-loads the resource and scope, then the cap and ordering, then the returned fields. No sentence is wasted.

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

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

With an output schema present and 100% param coverage, the description is more than sufficient for a one-parameter read tool. The only real gap is whether the 50-item cap implies results can be silently truncated, which matters for an agent deciding whether it has seen everything.

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 a single required parameter with 100% schema description coverage, so the schema already fully documents workspace_tag. The phrase "in one workspace" reinforces that the parameter scopes results to a single workspace but adds no syntax or format detail 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 ("Lists ... support tickets") along with scope ("this principal's", "in one workspace"), ordering, cap, and the fields returned. An agent can distinguish it from the write sibling submit_support_ticket without opening any schema.

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

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

The read-only framing and "this principal's" scoping make the intended use clear, and "not metered" signals it is cheap to call for status checks. It never names an alternative or states when not to use it, so it stops short of explicit routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds non-obvious behavior: newest-first ordering, include_expired defaulting to false, cursor+limit pagination, and the fact that the call is not metered. These are exactly the traits an agent cannot infer from the structured fields.

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

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

Three sentences, front-loaded with purpose and scope, then filtering/paging, then usage and downstream tools; every clause carries information. It is dense rather than padded, though the final sentence bundles several distinct ideas that could be split for faster scanning.

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

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

With an output schema present and rich annotations, the description need not describe return values; it instead supplies ordering, defaults, pagination, side-effect profile, and the recovery-after-timeout workflow. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is only 29% (session_ids and workspace_tag), but the description compensates by explaining the filter axes (session_ids, direction, state), the include_expired default, and how paging works with limit and cursor. It still does not characterize the state enum values or the limit bounds, so it is not fully self-sufficient.

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 ('Lists or recovers ... upload and download sessions'), scopes it to one workspace, and specifies ordering ('newest first'). The read-only listing framing clearly separates it from the create_upload_sessions / create_download_sessions siblings without needing to name 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?

Gives an explicit trigger ('use it after a timeout before repeating transfer creation') and reinforces it with a no-side-effect rationale ('listing changes nothing'), plus forward pointers to verify_standard_document, open_standard_document, and register. It lacks an explicit 'do not use when…' exclusion, but the condition that selects this tool is unambiguous.

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