Worthune Verified Financial Models

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

Annotations only provide generic flags (readOnly, idempotent, destructive). The description adds meaningful behavioral detail: the resource is persistent, validation rejects with JSON-path errors, and the payload should be fixed in one pass. It also discloses that the tool returns the household id, which is not present in the annotations or output schema.

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

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

Two dense sentences with no filler: the core action is front-loaded, then validation behavior is stated, then the return value and downstream usage are explained. Every clause contributes useful information for an agent deciding whether and how to call this tool.

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

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

For a three-parameter tool with a nested household object and no output schema, the description compensates well by referencing the full schema spec, summarizing its contents, explaining validation error behavior, and stating the returned id for use with sibling tools. An agent has enough information to construct and correct a valid household payload.

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

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

Input schema coverage is 100%, so the schema already documents the parameters. The description adds value by enumerating what the household-schema document contains (members, accounts by tax wrapper, liabilities, income/expense streams) and pointing to the spec, but it does not add much beyond that for label or api_key.

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

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

The description states a specific verb and resource: 'Create a persistent household resource from a household-schema document.' It clearly distinguishes this from sibling tools like get_household, replace_household, and project_household by identifying creation as the action and naming the returned id for use with those downstream operations.

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 creation context is clear: this tool is for creating a new persistent household from a schema document, not for reading or updating an existing one. It also explains that the returned household id is intended for use with get/replace/project_household, giving lifecycle context, though it does not explicitly state 'use replace_household instead for updates.'

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

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

Beyond the annotations, the description discloses important behavioral guarantees: illustrative inputs are 'labeled not-a-recommendation and is never applied silently', alternatives are 'ranked best-first by a checkable score', deltas name their baseline, projection-backed candidates link verifiable records, and exclusions are stated in the notes. This adds substantial transparency beyond the idempotentHint and destructiveHint 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 content is dense and all relevant, but the description is a single long paragraph with semicolon-separated details. A bulleted strategy list and separate behavioral notes would make it much easier to scan. It is front-loaded with the core purpose, but the structure does not support quick reference.

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

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

For a complex multi-strategy tool with no output schema, the description is unusually complete. It covers all seven strategies, their parameters and optionality, the ranked output format, evidence and baseline behavior, and important caveats like the illustrative asset-location set. An agent has enough information to invoke the tool correctly and interpret its results.

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

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

With only 29% schema description coverage, the description takes on the burden of documenting strategy-specific parameters and largely succeeds: it enumerates params for each strategy, including roth-ladder candidates, ss-claiming candidateAges, asset-location tax rates, tax-loss-harvesting rates, annual-gifting counts, and pension-election options. It does not fully explain shared fields like profile or assumptions, but the ambiguous strategy params are well covered.

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

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

The description opens with a specific verb and resource: 'Run a Household Coordination Engine strategy on a stored household' and clearly states the output: 'a ranked decision object with evidence records.' The strategy list and decision-object framing distinguish it from siblings like run_model, project_household, and narrate_decision.

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 clearly establishes the context: use this tool when you need to run one of the listed coordination strategies on a stored household and get a ranked decision. It does not explicitly name alternatives or exclusions, but the use case is concrete enough that an agent should not confuse it with generic projection or narration tools.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description strongly reinforces this with 'Nothing is written.' It goes beyond annotations by disclosing the three deterministic gates, the numeric-constant transcription guard, and the real import dry-run, giving the agent an accurate model of what happens before returning.

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

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

The description is dense but every sentence earns its place: purpose, input limits, deterministic gates, safety guarantee, and next-step instructions. It is front-loaded with the core purpose and provides critical behavior without 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?

Even with no output schema, the description tells the agent what to expect (a DRAFT mapping template plus an unmappedColumns honesty list), what safety gates apply, and how to proceed. Given the tool's moderate complexity and sibling set, this is complete enough for correct invocation and follow-through.

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?

Input schema description coverage is 100%, so the baseline is 3. The description reinforces sampleRecords semantics as 'column → string cell' and the 1-10 constraint, but it doesn't add meaningful detail beyond what the schema already provides for notes or api_key.

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

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

The description specifies a concrete verb and resource: AI drafts a mapping template from sample records for the import_households workflow. It clearly differentiates itself from siblings by labeling the output as a DRAFT and directing the final import to import_households.

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

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

It explicitly states the workflow context: use this tool to prepare a draft mapping, then run import_households yourself with dryRun: true over the full export. This both states when to use it and names the alternative/next step, leaving no ambiguity about its role.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds minimal extra behavior (that metadata is returned alongside the document), but does not mention error cases, response shape, or authorization requirements. With annotations carrying the safety burden, a 3 is appropriate.

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

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

The description is a single, economical sentence with the verb and resource front-loaded. Every word contributes; there is no wasted phrasing or redundant restating of the tool name.

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

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

For a simple read-by-id tool with one required parameter and strong annotations, the description sufficiently states what will be returned (the household document and its metadata). No output schema exists, so some return detail is helpful—and the description provides it, though it could mention not-found behavior or the need for an API key.

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

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

Schema description coverage is 100%, with 'id' documented as 'Household id from create_household' and 'api_key' as 'Worthune API key (wk_…)'. The description's 'by id' adds nothing beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('Fetch') with a clear resource ('a stored household document and its metadata') and identifies the lookup key ('by id'). It clearly distinguishes this read operation from mutation siblings like create_household and replace_household.

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 implies usage: you fetch a household when you have its id. It does not explicitly state when to use this tool versus alternatives like project_household or run_model, nor does it mention conditions like 'after create_household'. Schema documentation partially covers this with 'Household id from create_household', but the description itself lacks 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 readOnlyHint, idempotentHint, and destructiveHint, lowering the bar. The description adds useful behavioral context by explaining the composition of the contract (cross-field constraints, sentinel values, constants with sources) and the api_key requirement for include_spec, which is not fully covered by annotations.

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

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

The description is two sentences, front-loads the core purpose, and adds optional context in the second sentence. Every word earns its place with no redundancy or fluff.

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 there is no output schema, the description takes on the burden of describing the return value and does so thoroughly: required inputs, types, valid domains, cross-field constraints, sentinel values, and constants with sources. The include_spec flag and its access rule are also covered, making the tool self-sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant parameter-specific meaning beyond the schema; it mentions include_spec but the schema already describes its behavior and the api_key prerequisite. The extra content (government constants, sentinel values) describes outputs, not parameters.

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

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

The description opens with a specific verb and object: 'Get a model's machine-readable contract' and enumerates the contents (inputs, constraints, sentinel values, constants). This clearly distinguishes it from siblings like list_models, run_model, and verify_claim.

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 provides clear context on what the tool is for and how to extend its output via include_spec, but it does not explicitly state when to use this tool over its siblings or mention any exclusions. This meets the 'clear context, no exclusions' bar.

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 provide idempotentHint=true and destructiveHint=false, and the description meaningfully extends this by stating that re-runs skip already-imported keys and report householdId, imports never overwrite, and dryRun writes NOTHING. It also discloses the 200-household limit and deterministic template execution. This goes well beyond what annotations alone convey.

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

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

The description is dense and front-loaded: the dryRun-first workflow, batch limit, and two input shapes appear before lower-level detail. Every sentence contributes necessary operational or behavioral information, and the reference to docs/data-migration.md avoids inlining the full template spec. There is no filler.

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

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

For a complex bulk-import tool with 5 parameters, nested objects, and no output schema, the description is remarkably complete. It covers the write behavior, idempotency, never-overwrite guarantee, batch limit, two input forms, template determinism, and what reports are produced. The only slight gap is the exact response envelope, but the reference to per-row per-field reports and reported householdIds gives the agent enough to navigate.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description adds substantial semantic meaning beyond the schema: dryRun is a validation pass with no writes, importKey is a stable caller-provided id used for idempotency, and the template+records path executes a declarative mapping deterministically. It does not add much detail for api_key, but the schema already describes it.

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

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

The description opens with a specific verb and resource: 'Migrate a book (WS3.5): import up to 200 households in one call.' It clearly distinguishes this as a bulk migration operation versus the single-household sibling tools, and it names the two supported input shapes. The purpose is unambiguous and not a restatement of the tool name.

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

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

The description gives explicit workflow guidance: use dryRun first to validate and write nothing, iterate until the report is clean, then run for real. It also explains the choice between direct households[] and template + records. It does not explicitly contrast with sibling create_household, but the bulk-migration context and dryRun-first workflow make the intended usage clear.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds useful context beyond them: no API key required, optional id returns the full document, and omitting id returns all twelve summaries. There is no contradiction with the annotations.

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

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

The description is front-loaded with the core purpose and use cases, and the lengthy scenario list earns its place by helping an agent understand the variety of examples available. It is somewhat wordy but every sentence contributes.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers what the agent gets back (summaries or full document), auth requirements, and intended uses. No mission-critical information is missing.

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

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

The schema already describes the sole id parameter with 100% coverage, so the baseline is 3. The description's 'Pass an id to get the full document back' repeats the schema's meaning without adding format, examples, or value constraints.

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

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

The description clearly identifies the resource as twelve FICTIONAL example households and explains they exercise different planning-engine scenarios, which separates them from real user households. The combination of 'Pass an id...' and the schema's 'omit to list all twelve' makes both listing and detail-fetch behavior 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 explicitly provides two use cases: as a starting point for try_household_projection and as a worked shape when helping users describe their own households. It does not explicitly mention when not to use it or contrast with get_household, so it stops short of a 5.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds that it 'Returns model names and spec versions' and explains the Concordance-testing requirement. This provides useful behavioral context about the listing criteria and output.

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

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

The description is two sentences, front-loaded with the main purpose, and every sentence adds value: the first states what is listed, the second describes the return and next step. No wasted words.

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

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

Given no output schema, the description adequately covers return values and provides a usage pointer to 'get_model_contract'. It is complete for a simple list operation, though it does not mention pagination or filtering (unlikely needed with 0 params).

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

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

With zero parameters, the schema provides no parameter information, and the description also does not need to explain any. The baseline for 0 params is 4, and the description adds no confusing parameter semantics.

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

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

The description clearly states the tool lists 'Worthune's Concordance-tested financial calculation models', using a specific verb and resource. It distinguishes from siblings like 'get_model_contract' and 'run_model' by focusing on the enumeration of available models.

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 provides clear context for when to use the tool: before running a model, it suggests calling 'get_model_contract' first. It gives a logical sequence but does not explicitly exclude alternatives or state 'when not to use'.

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

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

The description is unusually explicit: it reveals the deterministic gate, the one-retry-then-refusal behavior, that narratives are 'never patched,' and that invented numbers reject the whole draft. This goes well beyond the readOnlyHint and destructiveHint annotations and gives the agent accurate expectations about failures and guarantees.

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 dense sentences front-load the core purpose, then pack the verification behavior and output promise with no filler. Every clause adds operational value: input options, safety mechanism, retry limit, and the reported claim count.

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 no output schema, the description covers inputs, validation order, retry/refusal behavior, and the fact that the response reports the number of checked claims. It stops short of specifying the full response shape or how the prose itself is returned, so a small gap remains.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds a little context by distinguishing stored decisions (decision_id) from inline decision objects and noting validation, but it does not substantially extend the schema's parameter documentation.

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

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

The description opens with 'The Verified Narrative: client- or advisor-ready prose for a stored decision (decision_id) or an inline decision object,' naming a specific deliverable, source, and inputs. This clearly distinguishes it from siblings like verify_claim by framing the output as a full narrative with a verification pass.

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 implies the tool is for producing an audience-ready narrative of a decision and lists the two accepted input forms, but it never explicitly states when to prefer it over siblings or when not to use it. No alternatives or exclusions are mentioned, so the agent is left to infer usage from purpose.

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

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

The description adds meaningful behavioral context beyond the annotations: it clarifies that entries are replaced or appended by id, that removals are entry-scoped, that expectedVersion is mandatory, and that the merged result is fully validated. The statement that 'a delta can never produce an invalid household' is a strong, non-obvious guarantee.

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

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

Two dense sentences pack the operation, scope, version requirement, and validation guarantee without filler. The core delta semantics are front-loaded, and the expectedVersion warning is placed immediately after the operation description.

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

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

For a mutation with nested objects and no output schema, this description covers the operations, versioning prerequisite, and post-validation contract well. It does not mention error behavior on version mismatch or auth-related details, but the essential information needed to call the tool correctly 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?

While the schema already describes set, remove, upsert, and api_key, the description reinforces the semantics and significantly clarifies expectedVersion by explaining why it is required and where to obtain it. It does not elaborate on id or api_key, but those are straightforward; overall it adds useful meaning beyond the schema.

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

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

The description uses a specific verb ('Apply a collection-level delta') and identifies the resource ('stored household') while enumerating the exact operations: set scalars, upsert entries, remove entries. It also differentiates itself from full-document replacement by stating 'without resending the whole document', which distinguishes it from the sibling replace_household.

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 clearly states that expectedVersion comes from get_household and is REQUIRED, giving the agent a direct prerequisite and read-before-patch workflow. It does not explicitly name alternatives like replace_household for full replacement, so while context is strong, explicit when-not/alternative guidance is absent.

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 indicate idempotent, non-destructive, read-write. The description adds meaningful behavior: determinism, seeded Monte Carlo reproducibility, always-named assumptionsSource, and every simplification listed in projection.assumptionsApplied. This goes beyond the annotations and gives the agent expectations about response content and repeatability.

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

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

The description is dense but front-loaded with the core action and outputs, then packs the assumptions modes and response contract into the second sentence. 'show your work' is stylistic but harmless and reinforces the transparency promise. No wasted sentences, though the long dash-heavy structure could be easier to parse.

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

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

For a complex nested-parameter tool with no output schema, the description does substantial work: it lists output categories, names the assumptionsSource and assumptionsApplied response fields, and explains all major invocation modes. It stops short of describing error behavior or return envelope, but an agent can confidently invoke the tool and interpret the result.

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

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

Schema description coverage is only 17%, so the description must compensate. It explains the assumptions alternatives (custom, profile, default) and the seeded Monte Carlo concept, and 'stored household' implies the id parameter. However, it does not explain horizon semantics (startYear, years), api_key, or the numeric meaning of fields like annualReturn, inflationRate, or returnVolatility, leaving those to the schema.

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

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

The description names a specific verb ('run'), a specific resource ('stored household'), and a concrete deliverable ('multi-year projection') with enumerated output categories (income, RMDs, tax, expenses, cash flow, net worth). This clearly distinguishes the tool from siblings like get_household or run_model even without an explicit sibling comparison.

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

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

The description gives clear usage context for choosing assumptions: pass your own, pin a profile by id+version, or omit both for the illustrative default. It also explains when Monte Carlo is relevant (seeded, same seed same result). It does not explicitly state when not to use this vsul alternative tools, but the guidance is clear for the primary decision an agent faces.

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 meaningfully adds conflict behavior beyond the annotations: full-document replacement and stale writes failing cleanly with the current version rather than clobbering. No contradiction with the provided false readOnly/idempotent hints; it leaves out auth/rate-limit detail, but 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?

One dense sentence front-loads the operation and then explains the concurrency contract with no filler. Every clause adds useful decision-relevant information.

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

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

For a 5-parameter mutating tool with no output schema, the description covers the essential workflow: what is replaced, where expectedVersion comes from, and what happens on conflict. It does not describe the success/error return shape, but that is not needed to select or invoke the tool correctly in most agent workflows.

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 40%, and the description compensates for the most important parameter (expectedVersion, sourced from get_household) while 'full-document replace' gives household meaning. It does not explain id, label, or api_key, though api_key is described in the schema; the optionality of expectedVersion in the schema is also left implicit.

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 action ('full-document replace') on a clear resource (household), and the optimistic-concurrency qualifier sets it apart from create/partial-update siblings. The phrase 'replace' and reference to get_household make the resource and workflow 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?

Clear context tells an agent that this is for replacing an existing household and that expectedVersion should come from get_household to avoid clobbering concurrent changes. It does not explicitly name alternatives such as create_household or project_household or state when to prefer them, so it stops short of a 5.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds rich behavior: out-of-domain requests are rejected (never clamped), the response echoes inputs/spec version/assumptions/sentinels/constants, and outputs are untouched engine results. This gives the agent a clear understanding of validation and return behavior far beyond what annotations declare.

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 four sentences, each earning its place: purpose, input requirements, response contents, and share link. It is front-loaded with the primary action and contains no redundant or filler text.

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

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

Even without an output schema, the description fully describes the response contents (echoes, spec version, assumptions, sentinels, sourced constants, untouched outputs). It also covers the critical input contract and provides usage context for scenario models. Combined with the rich schema and annotations, it gives a complete picture for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description meaningfully elaborates on the 'inputs' parameter by specifying contract requirements, all fields required, and rejection rather than clamping. It also reiterates that the api_key is only needed for non-free models, though this is already in the schema; the added contract semantics justify a score 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?

The description clearly states the tool runs a Concordance-tested calculation model with a specific verb ('Run') and resource ('calculation model'). It differentiates from siblings like get_model_contract (which provides contracts) and list_models (which lists models), making its 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?

The description explicitly references get_model_contract as a prerequisite, stating inputs must satisfy that contract, which tells the agent when to use this tool and what to do first. It also provides guidance for scenario models by suggesting sharing the interactive calculator link, though it does not explicitly mention when not to use the 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?

Beyond the annotations, the description discloses important behaviors: no API key, nothing stored, no id issued, deterministic output, and a reproducible evidence hash. It explains that the response includes assumptionsApplied and an evidence record, which is valuable context the annotations alone do not provide.

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

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

The description is dense but well organized: action first, followed by key constraints, response contents, and usage alternatives. It is longer than the minimum, but almost every sentence carries useful information, with only minor flourish like 'so you can show your work.'

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

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

For a complex tool with nested objects and no output schema, the description is complete enough for an agent to invoke it correctly. It describes what the response will contain, how results are reproducible, that no storage occurs, where to find an example input, and the persistent alternative.

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

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

The schema already provides descriptions for household, monteCarlo, and assumptions, covering 60% of parameters. The description adds high-level context like 'document you pass in' and 'seeded Monte Carlo,' but it does not add significant meaning for the policy or horizon parameters beyond what their names and schema structures imply.

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

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

The description opens with a specific verb and resource: 'Run the deterministic multi-year household projection on a document you pass in,' and lists the concrete outputs such as income, RMDs, Roth conversions, and net worth per year. It also distinguishes itself from persistent household tools by emphasizing that no household is created, no id issued, and no record is kept.

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

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

The description gives explicit usage context: this is the keyless, stateless projection surface, while 'For a household that persists — with an id, bulk import, webhooks and drift detection — see create_household.' It also directs users to list_example_households for a starting shape, clearly guiding tool selection.

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

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

Beyond the annotations (readOnly, idempotent, destructive=false), the description discloses return behaviors: 'each claim comes back verified, violated, or out-of-scope, with the engine's computed value as proof and a decision-record hash tying the verdict to this spec version and these inputs.' It also emphasizes 'this tool never guesses,' a key behavioral trait not otherwise stated.

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 intentionally structured: opening with the main purpose, then instructions, return details, out-of-scope explanation, and usage guidance. Every sentence contributes new information without repetition or filler.

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

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

No output schema exists, so the description carries the burden of explaining return values, which it does fully (verified/violated/out-of-scope, computed value, decision-record hash). It also covers the tool's closed-world principle ('never guesses') and differentiates from run_model, making the context complete for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context about the claims parameter structure ('{path, op, value}') and the verdict mapping (verified, violated, out-of-scope), which clarifies how claims are interpreted and what the result means. This goes beyond the schema definitions, especially given no output schema exists.

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

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

The description opens with a specific verb+resource: 'Verify claims about a model's outputs against the engine before presenting them to a user.' It clearly states the tool's function and distinguishes it from siblings by contrasting with run_model ('use run_model when you want the full output envelope').

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

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

Provides explicit when-to-use guidance: 'Use it to check a number you are about to state; use run_model when you want the full output envelope.' Also includes contextual timing ('before presenting them to a user') and explains the out-of-scope behavior, which informs when the tool is appropriate.

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