Worthune Verified Financial Models

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

The description discloses important non-obvious outcomes: the row is never deleted, it remains readable, it leaves the active-household meter, and it rejects further writes/projections. This goes beyond the annotations, which only flag the operation as mutating and destructive; the 'never deleted' wording refines the destructiveHint rather than contradicting it.

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 compact and front-loaded with the core action, followed by a useful behavioral clarification in parentheses. The only slightly redundant or confusing part is the 'same operation as DELETE' reference, which is informative for API mapping but muddies the 'never deleted' statement.

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 two-parameter operation with no output schema, the description covers the essential behavioral outcomes and the irreversible consequences. It could be more complete by stating the id parameter explicitly and clarifying the relationship to the DELETE endpoint, but no critical execution detail 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?

Only one of the two parameters has a schema description (api_key), and the tool description does not explicitly explain that id is the stored household id. The phrase 'a stored household' plus the archive_household name makes this inferable, but the description itself adds little direct parameter 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 opens with a specific verb and object—'Archive a stored household'—and immediately clarifies the exact semantics with the parenthetical about never deleting, remaining readable, leaving the active-household meter, and stopping writes/projections. This distinguishes it from sibling operations such as list, patch, project, or create, even though the endpoint reference to DELETE is slightly confusing.

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 behavior implies when to use it: to retire a household from active use while preserving the row for future reading. However, it never explicitly says 'use this instead of X' or 'use this when...', so an agent must infer the use case from the described effects.

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 substantial behavior beyond the sparse annotations: persistence, JSON-path validation errors, the returned household id, and conditional idempotency when importKey is reused. This is especially valuable because idempotentHint is false while the description accurately discloses the idempotent retry contract. No annotation contradiction is present.

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 compact, front-loaded with the core purpose, and every sentence carries information: resource type, source schema, validation behavior, return value, and downstream usage. There is no redundant restatement of the tool name or schema fields.

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 household object, no output schema, and a large sibling set, the description provides enough context to invoke it correctly: what valid input looks like, what errors look like, how idempotency works, and what is returned. The reference to the schema spec covers the detailed document structure. Missing sibling comparisons are a usage-guidance issue, not a completeness gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining what the household-schema document contains (members, accounts by tax wrapper, liabilities, income and expense streams) and by setting expectations for validation errors. It does not need to re-explain label, api_key, or importKey because the schema already documents them well.

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: it creates a persistent household resource from a household-schema document. It also clarifies what the returned id is for by naming get/replace/project_household. However, it does not explicitly differentiate this tool from siblings like import_households, patch_household, or replace_household, so it stops short of full sibling-level distinction.

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

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

The description implies the primary use case: create a new persistent household. It also gives practical guidance about validation (fix the payload in one pass) and retry semantics via importKey. But it does not explicitly say when to choose this over alternatives such as import_households for bulk imports or patch_household/replace_household 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?

The description goes well beyond the minimal annotations by explaining ranking behavior, baseline deltas, verifiable evidence records, exclusions in notes, and the illustrative-characteristics safeguard. It does not disclose whether the decision is persisted or what side effects occur, but annotations are also uninformative, so the rich behavioral detail earns a strong score.

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 long but every clause contributes necessary strategy-specific information. It is front-loaded with the main purpose, then organizes each strategy's parameters compactly, and ends with shared output behavior. No filler or repetition.

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

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

The description compensates for the lack of an output schema by explaining the ranked decision object, evidence records, deltas, and notes. It also covers all strategy variants and their required params. Missing details are limited to persistence semantics and how to resolve the stored household, which are minor given the tool's complexity.

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 coverage, the description carries heavy parameter responsibility and largely succeeds: every strategy's params are enumerated with types, optionality, and constraints. However, top-level parameters such as horizon, assumptions, profile, and api_key receive no added explanation beyond their schema names.

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

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

The description states a specific action — 'Run a Household Coordination Engine strategy on a stored household' — and clearly identifies the output: a ranked decision object with evidence records. The strategy list further disambiguates the tool from generic model or projection siblings.

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

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

Usage context is implied: use this tool when you need a ranked decision under a named objective. However, the description offers no explicit guidance about when to prefer this tool over alternatives like project_household, run_model, or get_decision, and no exclusions are stated.

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

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

Annotations already 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?

Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description discloses the important quirk that very old decisions may be returned hash-only and that the response explicitly says so. This is valuable behavioral context not available 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?

Three focused sentences, each carrying distinct information: payload contents, old-record hash-only behavior, and REST equivalence. The main purpose is front-loaded and there is no filler or repetition.

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

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

For a read-only single-resource tool with no output schema, the description gives a complete picture of what the caller receives, including the edge case for old decisions. It also points to verification workflows, making the return content actionable.

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 describes api_key but leaves decision_id with only type and range constraints. The description implies that decision_id selects a stored decision, but it does not explicitly explain the parameter semantics or how the decision object relates to the ID. The description helps somewhat but does not fully compensate for the undocumented required parameter.

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 tool as retrieving one stored decision in full, including the decision object, the household version, and the evidence record. It differentiates from list_decisions by emphasizing 'one stored decision' and explicitly equating it to GET /api/v1/decisions/{id}.

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 establishes clear context: use when you need a single complete decision with evidence, and notes the exact REST equivalent. It does not explicitly contrast with siblings like list_decisions or narrate_decision, but the singular, full-payload framing gives adequate 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 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, and the description strongly reinforces and extends this: it explicitly says 'nothing is stored,' 'Sums only — no new number of consequence,' and that as_of is 'echoed back.' It also maps the operation to a GET endpoint. No contradiction with 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 dense and front-loaded, with most sentences adding substantive information. The parenthetical 'the same drift reasons the weekly scan delivers' is somewhat convoluted and adds marginal value, but overall the description is appropriately sized for the tool's complexity.

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

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

For a read-only composite endpoint with no output schema, the description covers the key response sections, the as_of behavior, and the safety profile. It could be slightly clearer about the drift parenthetical and any output format limits, but an agent has enough to invoke the tool correctly.

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

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

Schema description coverage is 67%, with as_of and api_key already described. The description adds meaningful semantics for as_of by explaining that passing it 'pins the date' and that it is echoed back. The required id is not described in prose but is clear from the resource context and endpoint 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 description clearly states a specific verb and resource: it produces a composite 'household picture' containing balance sheet by wrapper/owner, income and spending, computation drift, newest decisions, and a data-quality report. This content list makes it unambiguous and distinguishes it from sibling tools like get_household or get_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 implies when this tool is useful—when an agent wants a comprehensive one-household snapshot—but it never explicitly says when to use this over alternatives like get_household or list_decisions. There are no exclusion conditions or named alternatives, so usage guidance is only implicit.

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, so the safety profile is covered. The description adds substantive behavioral context by explaining the conditional output when include_spec is set and the machine-readable content returned, which is valuable beyond 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?

Two tight sentences with front-loaded purpose. The first sentence states exactly what the tool returns, and the second adds the optional behavior without any filler or repetition of schema details.

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 description gives a clear picture of the return value even without an output schema, enumerating the contract sections and the optional markdown spec. Combined with the detailed parameter schema and safety annotations, everything an agent needs 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?

Schema description coverage is 100%, so the schema already documents model, api_key, and include_spec in detail. The description mostly explains the return content rather than adding new parameter-level meaning, so it does not need to compensate for missing schema information. 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 opens with a specific verb and resource: 'Get a model's machine-readable contract'. It then enumerates what the contract contains (required inputs, types, valid domains, cross-field constraints, sentinel values, government constants), making the tool's purpose concrete and distinct from sibling listing tools like list_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 makes the intended use clear—fetching a contract or adding the full specification via include_spec—but it never explicitly names alternative tools or states when not to use this one. It indirectly references list_models in the schema for the model parameter, but the description itself does not provide exclusion or 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 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the result is append-only, newest first, metadata-only, and includes specific fields. It does not mention pagination or limits, but for a read-only list tool this is a minor gap.

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

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

Three sentences pack in scope, ordering, field list, metadata-only caveat, sibling routing, and endpoint mapping. There is no filler and the most important behavioral facts come first.

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?

Despite having no output schema, the description names the return fields, the sort order, the append-only nature, and the alternative for full records. Combined with simple parameters and strong read-only annotations, nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so id and api_key are already documented. The description adds only mild context by showing id in the endpoint path ('households/{id}/decisions') and implying the household must already be stored. This is useful but does not materially extend 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 lists a specific resource ('history of coordination strategies run on a stored household') and a clear operation ('newest first' listing), and it explicitly distinguishes itself from get_decision by noting it returns metadata only. This is more than the title alone and clearly differentiates from the closest 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?

The description gives concrete guidance: use this for the append-only metadata history, and use get_decision when a full record is needed. It also maps the tool to a canonical REST endpoint, making the access pattern unambiguous. This is explicit enough for an agent to choose correctly.

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?

Annotations already convey readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context: the list omits documents, returns summary fields, and defaults to active households while the underlying API returns every status. This goes beyond the structured annotations without contradicting 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?

Two tightly packed sentences carry all essential information: resource, fields returned, sibling distinction, and status semantics. Every clause earns its place and the key distinction is front-loaded.

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

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

For a simple read-only list tool with annotations covering safety and no output schema, the description is complete: it states the returned fields, the default filter, how to override it, and when to use the sibling tool instead. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds the crucial default behavior of the status parameter ('Defaults to active households') and explains how to achieve an all-status listing, enriching the schema's enum with operational meaning.

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 ('List') and resource ('the organization's stored households') and enumerates the returned fields. It also explicitly differentiates itself from get_household, which returns one household in full, making the tool's scope 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 provides clear when-to-use guidance: use this for summary listings without documents, and use get_household for a full household. It also explains the status default and how to request all statuses, so the agent knows exactly how to navigate the status parameter.

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?

The description adds meaningful behavioral context beyond the annotations: it discloses determinism, seeded Monte Carlo reproducibility ('same seed, same result'), and that the response always names assumptionsSource and lists fired simplifications in projection.assumptionsApplied. These details align with idempotentHint and provide transparency the annotations alone do not.

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 with no fluff. It front-loads the core action and output components, then adds assumption-selection guidance and behavioral transparency. Every clause earns its place, including the compact 'show your work' closer.

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 seven parameters, nested objects, low schema coverage, and no output schema, the description provides a good high-level picture of outputs and transparency guarantees. However, it leaves several important invocation details—especially Monte Carlo sub-parameters, api_key handling, and horizon constraints—to the schema, making it adequate but not fully complete.

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

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

Schema description coverage is only 29%, so the description needs to compensate for under-documented parameters. It adds useful semantics for assumptions/profile modes but says nothing about the required id and horizon parameters, and it does not explain the monteCarlo object's sub-fields or policy details beyond what the schema already states.

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

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

The description names a specific verb ('Run'), a specific resource ('stored household'), and enumerates the projection outputs, making the tool's purpose clear. It does not explicitly distinguish itself from siblings like try_household_projection, though the 'stored household' phrasing hints at the difference.

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 context for how to invoke the tool: pass assumptions, pin a profile by id+version, or use the default, and optionally enable seeded Monte Carlo. However, it does not explicitly state when to prefer this tool over alternatives such as try_household_projection or run_model, nor does it list when-not-to-use conditions.

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?

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds substantial context: no API key, nothing stored, no id issued, no record kept, deterministic behavior, hash-reproducible evidence, and assumptionsApplied returned in the response. This goes well beyond what the structured annotations alone communicate.

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 lead sentence is front-loaded with the core action and output, followed by a compact no-storage guarantee and practical sibling links. It is dense but not bloated; the only mild redundancy is the two-part emphasis that nothing is stored.

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, keyless tool with no output schema, the description covers determinism, response contents, input shape guidance, and persistence alternatives. It falls slightly short by not naming project_household and by giving only a high-level sketch of returned projection data, but the schema fills many remaining details.

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 clarifies that household is 'a document you pass in' (not an ID) and notes that Monte Carlo is optional and seeded, and it points to list_example_households for the starting shape. However, it adds little about horizon, assumptions, or policy beyond what the schema already provides, and schema description coverage is only 60%, so those gaps are not fully compensated.

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 enumerates the computed outputs (income, RMDs, Roth conversions, taxes, expenses, amortization, deficit draw, net worth). It clearly distinguishes this keyless, stateless surface from create_household, which creates a persistent record, and points to list_example_households for input shape. The only minor ambiguity is that the sibling project_household is not explicitly referenced, but the core purpose is unmistakable.

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 routes to alternatives: 'Use list_example_households for a starting shape' and 'For a household that persists ... see create_household, which takes a key.' This gives clear context for when to use this ephemeral tool versus a persistent one. However, it does not mention the sibling project_household, so an agent may still be uncertain about the boundary between this tool and that one.

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.