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

Annotations already indicate this is not read-only and not idempotent. The description adds behavioral context beyond annotations: the server recomputes totals, and the `unit` must match the estimate's own measurement system. This is valuable operational behavior not otherwise disclosed.

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

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

The description is three concise sentences with no filler. The core action is front-loaded, followed by the most important usage caveat and a behavioral side effect. Every sentence carries meaningful information.

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

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

Given the schema richly defines required parameters, enums, and constraints, plus annotations describe mutability, the description covers the most critical operational context: how `unit` should be chosen and that totals will be recomputed. It does not explain response or output, but for an add-line tool with no output schema this is a suitable gap.

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

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

Schema description coverage is 0%, and the description only adds semantic precision for the `unit` parameter. The other parameters rely on self-explanatory names and schema constraints. This is minimally adequate, but leaves several parameters without description-level semantic context.

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 ('Add'), a distinct resource ('one line to a generated estimate'), and the fact that totals are recomputed. This clearly identifies the operation and distinguishes it by verb from update/delete sibling tools, though it does not explicitly name those alternatives.

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 to use the tool (adding a line to a generated estimate) and offers important in-use guidance ('read an existing line... rather than guessing'). However, it does not explicitly explain when to choose this tool over update_estimate_line or delete_estimate_line, leaving selection between siblings to inference.

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

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

The description adds meaningful behavior beyond the annotations: tokens arrive asynchronously, the payment may be automatically charged or require human checkout, and the key's spend cap cannot be raised by a purchase. It also documents the two main response outcomes (`charged` and `requires_human`) without an 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?

The description is three sentences with no filler. It leads with the primary action, follows with restrictions, and then explains response behavior and the subsequent polling step.

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 supplies response semantics, asynchronous delivery, and the follow-up polling instruction. Together with the schema's package guidance, an agent has enough context to call this 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?

The input schema already fully documents the single `package` parameter, including its source (`list_token_packages`) and an example value (`"600"`). The description does not need to add parameter-level detail, so the baseline of 3 is appropriate.

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

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

The opening phrase "Buy one token package for this key's wallet" names a specific action, resource, and target object. It is immediately distinguishable from sibling tools like list_token_packages and get_balance.

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 preconditions: the key must have purchasing enabled and the purchase cannot exceed the key's remaining spend cap. It also tells the agent to poll get_balance afterward, clarifying what happens after this tool completes.

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 it as a write operation, but the description adds important behavior beyond that: reusing an existing name is refused, so the agent should not retry the same name. It also clearly states that `goals` is a free-form brief, which is genuinely useful context.

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

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

The description is short, front-loaded with the main purpose, and each sentence adds a distinct piece of applicable information. There is no filler or repetition that outweighs the guidance.

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?

This is a low-complexity creation tool with a fully documented schema and clear uniqueness constraints, so the agent can confidently make a valid call. It does not describe the returned object or next steps after creation, but for the call itself that is a relatively minor 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 schema already documents all parameters. The description adds value by explaining the rejection behavior for duplicate names, advising the agent to choose a distinct name, and clarifying that `goals` is the free-form brief.

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

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

The description uses a specific verb and resource: 'Create a building,' then adds the clarifying detail '(a house to design).' This immediately distinguishes the building entity from related objects like designs, jobs, and renders.

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 purpose phrase implies this tool is the entry point for creating a house, but it never explicitly states when to use this tool versus alternatives such as start_design or delete_building. The unique-name guidance is operational retry advice, not tool-selection 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?

Description adds substantial behavioral context beyond annotations: it discloses server-side soft deletion, that a human can undo it, that this tool itself cannot undo it, and that token spend is not refunded. It also details exactly what is affected (all sub-resources), which is more informative than the raw destructiveHint flag alone.

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

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

Three sentences, front-loaded with the core action and its scope, followed by necessary caveats. No fluff or repetition. Slightly more elaborate than the bare minimum, but each detail earns its place by clarifying material consequences of the operation.

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

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

For a one-parameter destructive tool with no output schema, the description covers the essential behavioral contract: what gets deleted, whether it is reversible, who can reverse it, and whether consumer tokens are lost. Nothing that an agent needs to decide whether to call this tool or to anticipate its side effects 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 0% and the description offers no additional meaning for building_id; it only repeats the concept of deleting a building. The tool never explains where to obtain building_id or whether it refers to an internal identifier, job-related ID, or app-facing ID. This is a gap because the description carries the full burden for parameter semantics and does not compensate beyond the self-explanatory name.

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

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

States a specific verb (delete) and resource (building) and defines the scope with an explicit list of all deleted sub-resources: photos, designs, renders, estimates, albums. This clearly distinguishes it from siblings like delete_render or delete_design, which handle a single sub-resource, and makes the cascade behavior explicit.

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

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

The description provides clear context on what the operation entails, such as soft deletion and non-refundability, so an agent can infer when to use it for bulk building removal. However, it never explicitly says when not to use it or names alternatives, like use delete_design for just a design. The guidance is implied through the enumerations of sub-resources and sibling names, not stated directly.

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

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

Annotations already carry destructiveHint=true, readOnlyHint=false, and idempotentHint=true; the description adds genuinely non-inferable context: the deletion is soft on the server side, reversible by a person in the app, and irreversible via this tool. This is exactly the kind of post-action consequence disclosure annotations don't 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?

Two tightly-packed sentences with zero filler: action and cascade are front-loaded, followed by the soft-delete undo caveat. Every sentence earns its place and the ordering correctly prioritizes the core behavior before the reversibility warning.

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 essential facts are present — what is deleted, what cascades, and reversibility — but for a destructive, idempotent tool with 0% parameter coverage and no output schema, it omits downstream consequences (e.g., effects on references from jobs, albums, or estimates) and any error conditions. The parameter-semantics gap is the main completeness hole for an agent attempting a correct call.

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

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

Schema coverage is 0% — both design_id and building_id are bare strings — and the description never explains their roles or why both are required. For a cascade delete, an agent is left guessing whether building_id scopes the lookup, guards authorization, or is merely redundant, which a destructive action should not leave ambiguous.

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

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

The description states a specific verb ('delete'), the exact resource ('one design (concept) of a building'), and the scope of the action ('with the renders under it'). The parenthetical explaining 'design' as a 'concept' plus the cascade note clearly distinguish it from siblings like delete_render and delete_building without opening their schemas.

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

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

The phrase 'with the renders under it' signals this is the design-level deletion tool versus the render-level sibling delete_render, but no alternative is named and no when-not-to-use condition is stated. Selection guidance is implied through the cascade scope rather than explicitly routed.

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

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

It states that 'Totals are recomputed by the server', which is substantive behavioral context beyond the annotations. The destructiveHint and readOnlyHint are already annotated, and the description aligns with them, clarifying the post-operation effect.

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

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

Two sentences, both purposeful: one identifies the action, the other communicates the critical side effect. No wasted words or redundancy.

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

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

For a simple two-parameter deletion operation, the description covers the essential behavior and server-side consequence. There is no output schema, but explaining return values is unnecessary here; minor missing detail such as whether removal is reversible is mitigated by the idempotent/destructive annotations.

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

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

Schema description coverage is 0%, but the parameter names line_id and estimate_id are highly self-descriptive, and the description reinforces their roles by mentioning 'line' and 'estimate'. No explicit parameter-level guidance is added, but with only two obvious parameters the gap is acceptable.

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 clear verb ('Remove') and target resource ('one line from a generated estimate'), immediately distinguishing this from add_estimate_line and update_estimate_line. It states exactly what the tool does in a single line.

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: call this when you need to remove a line item from an estimate, and the qualifier 'generated' provides some context. However, it does not explicitly mention when not to use it or contrast it with add/update estimate line tools.

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

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

The description goes beyond the annotations by explaining this is a soft deletion, that a human can undo it in the app, and that this tool cannot undo it. It also discloses the side effect on the design's main render, which is valuable behavioral context beyond destructiveHint and idempotentHint.

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

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

The description is three compact sentences with no filler. Each sentence adds a distinct fact: the action, the design-draft side effect, and the soft-deletion caveat.

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 a single parameter, no output schema, and annotations covering safety semantics, the description supplies all necessary operational context: what gets deleted, what happens to the parent design, and what cannot be undone.

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

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

The input schema has only render_id with no description, and the schema coverage is 0%, so the description should compensate. It implies that render_id identifies the render to delete, but it does not explicitly explain the meaning of the ID or how it relates to 'main render' versus other renders.

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 specific verb and resource, 'Delete one render,' which clearly defines what the tool does. It further distinguishes the action from sibling tools like delete_design and delete_building by explaining the special effect of deleting the main render on the parent design.

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 clarifies the context: deleting the main render returns the design to draft, so it can be rendered again without a new design. This gives a practical reason to use the tool, though it does not explicitly name alternatives or 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 annotations already flag this as a read-only, open-world operation. The description adds useful behavioral context by explaining that `is_admissible` is the server-authoritative answer and should be trusted over manual comparison. It does not discuss authentication or rate-limit behavior, but that is minor for a zero-parameter read tool.

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

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

The description is two compact sentences with no filler. It front-loads the core purpose and immediately adds the single most important usage nuance: trust `is_admissible` over manually comparing the numbers.

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

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

For a no-parameter tool without an output schema, this description is sufficient. It describes the key output concepts (`balance`, `cap`, `is_admissible`) and tells the agent which one to use for decision-making, so an agent can invoke and interpret the result 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?

There are zero parameters and schema description coverage is 100%, so there is nothing the description needs to explain about inputs. This matches the expected baseline for a parameter-free tool.

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: 'the api-scope balance of the account and the cap of this key'. It lets the agent understand this is a wallet/balance check, but it lacks an explicit verb and does not directly name alternatives to distinguish it from sibling tools.

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

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

The intended usage is implied: `is_admissible` tells the agent whether the next paid call will be accepted, so it reads as a pre-payment check. However, the description does not explicitly say when to use `get_balance` instead of related tools such as `list_token_packages` or `buy_tokens`, nor does it include when-not/exclusion 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 and openWorldHint. The description adds context on what the read returns, which aligns with the read-only nature. It also adds a useful cross-tool detail about the `unit` display code for reuse in add_estimate_line.

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

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

Three sentences, each with a distinct job: describe payload, distinguish from sibling, and provide cross-tool reuse information. 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 simple single-parameter read tool, the description covers what is returned, positions the tool among siblings, and provides a usage hint. It omits only minor context such as error behavior or where estimate_id originates.

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 for the single estimate_id parameter is 0%, and the description does not explicitly explain estimate_id or how to obtain it. The parameter is largely self-explanatory from the tool name and title, but the description does not add 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?

Description clearly states the tool returns the finished estimate with totals, area, duration, and line items. It explicitly contrasts with get_job, implying this tool is the only one for actual estimate content, so an agent can distinguish it from siblings.

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

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

The description gives direct usage guidance: use this to see what was estimated, and explicitly excludes get_job since that only reports status, never content. This is a clear when-to-use vs. alternative.

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

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

The description goes far beyond annotations by adding per-kind success statuses (`completed` vs `ready`), failure semantics (`error`, `error_code`), pacing behavior (`expected_seconds`), and the important property that `result_url` is permanent, unexpiring, shared, and non-recallable. This is rich behavioral transparency.

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?

Every sentence adds a distinct, decision-relevant fact: success semantics, failure semantics, polling cadence, and URL permanence. The description is long but well organized with the essential operation first, and 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?

There is no output schema, so the description carries the full burden of explaining response behavior, and it does: success statuses, failure fields, expected-wait semantics, and permanent result URL behavior. A capable agent has everything needed to poll correctly and decide when to stop.

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

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

Schema coverage is only 33%, and the description compensates for the most important parameters: it explains the `kind` enum values and the rule that an album lookup requires `design_id`. `job_id` is not described, but it is an obvious identifier and is required by the schema, so the gap is minor.

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?

Starts with a specific verb and resource: 'Poll one queued job.' It then clarifies that the job kind can be a render, estimate, or album, which removes ambiguity about what the tool returns and clearly separates it from sibling tools like list_jobs.

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 strong operational guidance: stop polling on `completed`, `ready`, or `failed`; the expected wait can be paced via `expected_seconds` for render and album jobs; album lookups require `design_id`. It does not explicitly name alternatives to prefer when a set of jobs is needed instead of one, so the routing guidance is slightly incomplete.

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

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

Annotations already cover readOnlyHint=true and openWorldHint=true, so the base safety profile is known. The description adds meaningful behavior beyond that: main_render_id is null until a render finishes, main_render_url is permanent, unsignable, and not recallable once shared, and per-render state deliberately belongs to get_job. This is valuable context without contradicting 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 three sentences long and every sentence contributes: the first defines the result, the second explains field semantics and downstream usage, and the third routes user to get_job for per-render state. There is minimal fluff, though it is slightly dense and could be simplified without losing much.

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 one simple required parameter and no output schema, the description provides substantial context: it explains the key fields, their semantics, and the relationship to sibling tools. The main missing piece is any explicit explanation of how the building_id relates to the returned designs, but given the simple single-parameter structure this is a minor gap.

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

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

The schema has only one parameter, building_id, with 0% schema description coverage. The description only indirectly refers to it via 'of a building' and relies on the parameter name and tool title for meaning. It does not explicitly document what building_id is, where it comes from, or any format constraints, so it only partially compensates for the missing schema descriptions.

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

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

The description clearly states that the tool returns all designs of a building with their renders, making the resource and output explicit. It further distinguishes itself by explaining that this is the source of render IDs used by order_estimate, order_album, and refine_design. This is specific enough to differentiate from siblings like list_jobs and get_job.

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 when-to-use guidance: use this tool when you need render IDs for order_estimate, order_album, or refine_design. It also provides when-not-to-use guidance and an alternative, stating that per-render state is not here and to poll get_job for that. This is exactly the kind of routing the dimension asks for.

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

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

Annotations already declare readOnlyHint, so no contradiction there. The description adds useful behavioral context beyond annotations: unfinished jobs appear first, and each row carries kind, design_id, and building_id. It does not mention pagination or ordering beyond 'unfinished first', but the core behavior is transparent.

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?

Every sentence earns its place: purpose and ordering in the first sentence, the recovery use case and returned row fields in the second, and sibling routing in the third. It is compact, front-loaded, and contains 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 simple read-only list tool with no output schema, the description covers the main things an agent needs: what comes back (fields per row), ordering, and how to move to a single-job tool. It does not mention limit semantics or whether there are more results, but the two optional parameters are simple and the tool's purpose is sufficiently complete.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not fully. It relates the `kind` enum values by naming renders, estimates, and albums, but never states that the `kind` parameter filters the list or explains `limit`'s semantics beyond what the schema already says. The agent is still left to infer how these parameters affect the result.

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 and resource ('Recent jobs across the account') and defines the exact content: renders, estimates, and albums in one list. It differentiates itself from get_job by noting that this is the collection-level view while get_job handles a single known job.

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

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

It gives a clear usage context ('Use it to catch up after a restart') and explicitly points to the sibling alternative ('Use get_job to poll a single known job'). The description also explains why this tool is useful: each row includes the identifiers get_job asks for.

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

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

The description adds meaningful behavior beyond the readOnlyHint annotation by stating that token packages and prices change, so an agent should not cache or assume fixed data. It also clarifies that results are account-specific. This is useful behavioral detail for a read-only list tool.

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

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

Two sentences, with the core behavior front-loaded and the operational warning in the second sentence. Every part contributes value without unnecessary detail.

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

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

For a parameterless read-only list, the description completely covers what the tool returns, its scope, and its place in the workflow before buying tokens. The absence of an output schema is acceptable because the description already states the key output dimensions: price and token count.

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

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

The tool has zero parameters, so the description does not need to explain parameter meaning. It still adds context by noting the list is tied to the current account, which helps the agent understand implicit scope.

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 token packages available for purchase and what each entry contains: price and token count. It also names the resource ('token packages') and the intended account scope, making it distinguishable from sibling tools like buy_tokens.

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 instructs to read this tool before calling buy_tokens and warns against assuming a static package ladder. This provides clear usage context, though it does not exhaustively discuss when not to use the tool beyond this scenario.

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 explains important behaviors: the estimate fallback to the newest finished estimate, the refusal without a completed render, the inconsistent application of requirements with a notice in the response, and the permanent public link. This gives the agent a substantially richer model of side effects and failure modes.

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

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

The description is detailed but every sentence carries operational relevance: it defines the output, the prerequisites, the estimate fallback, and the requirements caveat. It is front-loaded with the core purpose, though the long clauses around API failure and notice wording are slightly dense.

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 covers the main return behavior, prerequisites, default price-source behavior, and an important API quirk, which is strong without an output schema. It does not explain the two boolean parameters or the default language, so an agent invoking with richer intent will have incomplete context.

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

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

The description adds useful meaning for estimate_id (fallback behavior), render_ids (the named renders), design_id (must have a completed main render), and requirements (not honoured on every account). However, with schema coverage at only 29%, it leaves language, include_estimate, and include_blueprints unexplained, so an agent must still guess at their purpose.

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

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

The description states a specific action and resource: turn named renders into a PDF album/blueprint containing materials, facade build-up, safety notes, and regulatory references. It also reinforces the kind of artifact ('the document a crew builds from'), which differentiates it from sibling tools like order_estimate.

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 conditions: a completed main render is required, an estimate_id should be supplied, and behavior differs across accounts. It does not explicitly contrast this tool with siblings such as order_estimate, but it does establish when the tool is appropriate and what prerequisites must exist.

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 disclose safety traits (write, non-idempotent, non-destructive) but not the nontrivial defaulting behavior. The description usefully explains that currency and measurement follow the building's country, language follows the account, and unspecified values must be omitted rather than guessed.

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

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

The opening sentence is specific and front-loaded, and the defaulting rules are important. However, the final 'money follows the house, the words follow the reader' sentence is a poetic restatement of the same rule and adds little for an AI agent.

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 covers the most ambiguous aspect — defaulting behavior — which is helpful for faithful invocation. However, the tool has seven parameters, no output schema, and unclear effects, so the agent is left guessing about whether a new estimate is created and what the response contains.

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 14% of parameters described in the schema, the description partially compensates by explaining currency, language, and measurement_system defaults. It does not clarify the relationship between design_id, building_id, and render_ids, nor the meaning or format of special_requirements.

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 clear verb and object: 'Price the design, line by line, in materials and labour, for the renders you name.' It also clarifies scope by saying the figures come from the design itself, which separates it from manual line-item editing. It does not explicitly name a sibling, but the purpose is unambiguous.

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

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

The description implies when to use the tool: when you want an estimate derived from a design and its specified renders, rather than a manually assembled estimate. However, it never explicitly tells the agent when not to use it or points to alternatives such as get_estimate or add_estimate_line.

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

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

Beyond the annotations, it discloses that the tool queues a render, returns a new job id, stores each step as its own design, and never overwrites the previous picture. It also states the refusal behavior for unfinished parent renders and the merge semantics: what is not mentioned stays as it is.

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 efficient and front-loaded with the core use case. It covers a lot of behavioral detail in one paragraph; slightly better formatting with separation of input modes would make it 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 9-parameter mutation tool with no output schema, the description explains the result contract—new job id plus design_id—and important state behavior such as no overwriting and refusal of unfinished parents. An agent has enough to invoke it correctly without guessing.

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

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

Schema coverage is only 56%, but the description compensates by clarifying the render_id/design_id/building_id relationships and the meaning of styles, colors, and brands as optional change-only inputs. The seed parameter is not covered, giving this a 4 rather than a 5.

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

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

The description opens with a specific verb and resource: 'Revise a finished design in words' and gives concrete examples. It explicitly names start_design as what this tool is not, making it easy to distinguish 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?

It explicitly says this is the tool 'for every step after the first, not start_design', giving a clear selection rule. It also explains the two valid invocation paths (render_id or design_id+building_id) and the precondition that the parent render must be finished.

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 reveals exactly how the tool behaves: it is free, works even on an empty wallet, does not generate a human reply, and returns only a quotable reference. It also instructs the agent on how to structure a report. This goes well beyond the bare annotations and does not contradict 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?

The description is longer than a typical simple tool, but this length is justified by the complexity of reporting failure conditions and by the need to encode a behavioral contract (free, empty wallet, reference result). It is front-loaded, starting with the purpose, and each clause adds either clarity, contrast, or trace evidence. Slightly more trimmed than this would be possible, but the current size is efficient given the subject.

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 reporting tool with no output schema, the description is complete: it defines what the call produces, what to include in the message and context, what is not handled, and why the free/instant/usage characteristics matter for the caller. There is no relevant gap needed to call 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 coverage is low (33%), but the description compensates with usable guidance for the `message` field ('Say what was attempted, what was expected and what happened instead') and for `context` ('put the tool name and the ids in context so the report can be traced'). The `category` parameter is not defined, but its enum values are self-explanatory, and the schema already explains `message`. Overall the description adds meaningful parameter semantics on top of a sparse 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 precise, specific statement: 'Report something wrong with this API itself', followed by concrete examples that make the intent unambiguous. It also clearly distinguishes the tool from people-facing or account-related contact, so it is easy to tell apart from the other design/order/build tools in the sibling list.

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

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

The description gives explicit conditions for use ('reported the moment it happens', 'a call that only works on the second try') and states a direct exclusion: 'This is not the way to reach a person about an account or a charge'. Although no alternative sibling is named, none exists among the listed tools, so the exclusion and concrete use cases are sufficient 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 indicate the tool is not a read-only, idempotent operation, and the description adds useful behavioral context: it creates a new design concept, queues async work, and returns a job id to poll. It also explains that the render is a consequence of a design decision rather than a free-standing picture, which sets user expectations without contradicting 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 purpose and then flows into causing behavior, return protocol, parameter details, and sibling routing. It is longer than the minimum but each sentence earns its place; the only slightly expendable part is the country/build-up rationale, which arguably strengthens semantic clarity rather than wasting words.

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

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

Given that there is no output schema, the description correctly covers the return shape ('returns a job id to poll with get_job') and the async queuing model. It also highlights the alternative refine_design path. Some dependencies are only implicit (building_id, view_id, style_ids), and it doesn't mention credit/token consumption, but for selecting and invoking the tool the description is sufficiently complete.

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

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

With only 50% schema description coverage, the description compensates well for the most nuanced parameters: prompt, colors (including format strings, lead role, and 60/30/10 ordering), brand_selections (product tuple format), and seed ('omit unless reproducing'). The less opaque parameters like view_id and render_effort are already described in the schema or are self-evident; only style_ids and building_id lack explicit coverage in either the schema or description.

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: 'Design the exterior of this house on a chosen view, and show the result as a picture,' then clarifies it 'creates a new design (concept) and queues the work.' It also differentiates from refine_design by explicitly stating when to use that sibling tool instead, so an agent can tell them apart.

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 direct when-to-use guidance: use this for a new design on a chosen view, poll with get_job, and use refine_design to modify an existing render. It also gives a conditional parameter rule ('Omit seed unless reproducing an earlier render'), which further helps correct invocation.

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 the operation is not read-only and is destructive. The description adds meaningful behavior beyond those annotations: it states that only passed fields change and that the server recomputes totals. This helps the agent understand the update semantics and important side effect.

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 concise sentences, front-loaded with the core purpose and immediately followed by the most important operational nuance. There is no filler or redundant restatement of the tool title.

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

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

Given the moderate complexity of 8 parameters, the description is sufficient for selecting and using the tool, especially with the annotation hints present. It covers scope, partial update behavior, and server recomputation. It could have been more complete with an example or explicit mention of the required identifiers, but these are evident from the schema.

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

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

The schema itself has no parameter descriptions (0% coverage), but the description partially compensates by listing the modifiable fields: name, quantity, unit, unit price, category, and section. It explains that only supplied fields update, but it does not clarify the role of estimate_id and line_id or the constraints on values, which remain only in the schema.

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

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

The description states a specific verb ('Change'), the resource ('one line of a generated estimate'), and explicitly enumerates which fields can be modified. This clearly distinguishes the tool from sibling add_estimate_line and delete_estimate_line without ambiguity.

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 it is used for modifying an existing line, and 'Only the fields passed are changed' clarifies partial update behavior. However, it does not state when to prefer this tool over add_estimate_line or delete_estimate_line, nor does it mention any prerequisites such as whether the estimate must be generated first.

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

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

Beyond the annotations, the description discloses asynchronous three-phase execution, the accepted/rejected result states, the permanence consequence, bounded wait behavior, and a retry-identent. This is exactly the kind of operational detail an agent cannot infer from the schema or 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 action and wait expectation, then adds dense, non-repetitive details about state, retries, and behavior. Every sentence earns its place; none of the input schema is simply copied back.

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?

Without an output schema, the description still covers the important result states: accepted, rejected, and pending, plus the no-dup resume retry. It does not detail low-level failure modes such as missing building IDs or invalid bytes, but for a three-parameter upload tool this is nearly 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?

The schema already documents file_path and building_id, and the description adds value by explaining the validation/pending behavior around the call and the same-file retry. The one gap is that wait_for_validation=false is not explained, so the default-true path is documented but the alternate path is not.

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

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

The first sentence defines a precise verb and object: 'Upload an exterior photo of the building and wait for it to be validated.' This goes beyond a tautology and clearly sets the tool apart from siblings like create_building or report_problem because it is specifically the building-photo upload flow.

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: a local file path is required, the photo must be of the building, validation is expected, and retries with the same file resume the existing view rather than creating duplicates. It does not explicitly say when not to use it or name an alternative, but the context is strong enough that an agent can select it 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?

The description adds important behavior beyond what the annotations provide: it costs tokens like a render, it runs asynchronously, it returns a pollable job, and it refuses invalid inputs with an explanation. This is exactly the kind of non-obvious behavior an agent needs to know.

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: the core action comes first, followed by cost/async behavior and refusal conditions. Every sentence earns its place without redundancy.

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

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

With no output schema, the description still tells the agent how to follow up by polling the returned job with get_job. It does not explain the exact result naming or whether the original render is preserved, but those are not essential 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?

The schema describes render_id only as a string, with 0% coverage, but the description compensates by tying the parameter to a completed, not-yet-upscaled render. For a single self-descriptive required identifier, this is enough semantic context.

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

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

The description identifies a specific verb-resource operation: 'Enlarge a completed render to a higher resolution.' It also narrows the scope by stating that already-upscaled and unfinished renders are refused, so an agent can distinguish what this tool is for.

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 valid usage conditions: the render must be completed and not already upscaled. It also tells the agent to poll the returned job with get_job. It does not explicitly name an alternative for creating a brand new high-resolution render, but the guidance is clear enough for correct tool selection.

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