Ferret

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

Annotations only declare it is a non-read, non-destructive, closed-world write. The description adds real behavioral context beyond that: the scan is then marked done (a state transition), each new item records its room-scan provenance, and only user-chosen items should be passed. It does not say what happens if the scan was already consumed or whether the batch is atomic, leaving some behavioral gaps.

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

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

Front-loaded with the action, then preconditions, side effects, and return value in a single tight passage with no filler. The em-dash clauses make it slightly dense but nothing is redundant.

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

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

For a non-destructive write tool with a fully documented schema and no output schema, it covers purpose, precondition, side effects, and the return value ('the items made'). Only error and idempotency behavior on an already-completed scan is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning: the name field may carry the person's correction rather than the scan's original text, and categoryId may be supplied optionally, both of which clarify how to populate the schema fields in practice.

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

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

States a specific verb and resource — adds the chosen items from a ready room scan into that scan's room or box — and frames it as the downstream step of the scan workflow, implicitly separating it from scan_room (scanning) and room_scan_results (reviewing). The mention that names can be corrected and a categoryId supplied further pins down what the call does.

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

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

Gives a clear precondition: 'Only after the person has confirmed the list,' which is exactly the gating condition an agent needs before writing. It does not name an alternative such as create_item for one-off additions, so the routing guidance is contextual rather than explicit.

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

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

Annotations only declare this is a non-destructive write with no external side effects. The description adds the critical behavior an agent cannot infer: the item is saved immediately as "New item", vision runs asynchronously, results appear after ~20 seconds via get_item, and update_item applies the confirmed values.

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 that are well front-loaded with the action, then the async lifecycle, then the sibling disambiguation. Slightly packed, and the trailing placement sentence reads as an abrupt addendum, but nothing is wasteful.

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

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

With no output schema, the description carries the return path itself: the immediate write, the background vision pass, and the ~20 second get_item/update_item confirmation loop. For a 5-parameter async ingestion tool, that is everything an agent needs.

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 baseline is 3. The description adds a genuine cross-parameter constraint not encoded in the schema — that locationId or containerItemId should be supplied — plus the default naming behavior when name is omitted.

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?

"Creates a new item from a photo" is a specific verb+resource, and the description immediately distinguishes it from add_photo (existing inventory item) and implicitly from create_item (no photo). An agent knows exactly what this does without opening the schema.

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

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

Explicit trigger ("when the person sends a picture of something to add"), explicit exclusion with a named alternative ("for a photo of something already in the inventory use add_photo"), and a prerequisite ("Put it somewhere with locationId or containerItemId").

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

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

Annotations only declare a non-destructive write; the description adds the computed default for dueOn, the 'whichever comes first' rule for combined time+usage intervals, and downstream visibility (what_needs_attention, household reminders). It does not say what happens on a duplicate title or near-duplicate, which is the one behavioral gap for a create tool that relies on a manual dedupe step.

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

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

Dense but well ordered: what is created and where, then recurrence mode, then default due date, then the usage-based variant, then dedupe and downstream visibility. The usage-based sentence stacks several clauses and is the only place readability slips.

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 12-parameter create tool with no output schema and only generic annotations, the description covers the decision-relevant parts: target selection, recurrence mode, defaults, prerequisites, and dedupe. Remaining secondary fields are fully documented in the schema, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so most semantics are already in the schema. The description adds genuine cross-parameter logic (intervalCount+intervalUnit as a pair, usageEvery requiring itemId, dueOn derived from those), but it does not touch attachmentId, providerId, partItemId/partQuantity, or notes, leaving those to the schema alone. Baseline 3 fits since the schema carries most of the load.

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?

Opening verb+resource ("Adds upkeep to track") plus explicit target scoping (itemId, locationId, or whole household) makes clear exactly what is created. Siblings add_maintenance vs list_maintenance vs complete_maintenance are trivially separable from this text.

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

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

Gives explicit pre-call checks ("Check list_maintenance first so you don't add it twice") and prerequisite ordering for usage-based tasks (set usageUnit via update_item, log a reading via record_reading first). Also states the alternative shape: give interval fields for repeats, neither for a one-off.

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

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

Annotations only declare readonly=false, destructive=false, openWorld=false; the description adds genuinely new behavior — asynchronous background vision processing, roughly a 20-second latency before results appear, and that suggestions are advisory rather than auto-applied. It also notes the call counts as AI actions when AI is on, which is quota-relevant context absent from the annotations. It does not cover payload size limits or failure behavior for unreadable images.

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

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

Four sentences, all load-bearing: purpose first, then the async read-back flow, then the sibling exclusion, then the AI-action billing note. No restatement of the title 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?

For a four-parameter mutation tool with no output schema, the description covers the key unknowns: that the call returns immediately while analysis is deferred, where the results surface (get_item), and how to commit them (update_item). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and every property is described, so the schema already carries parameter meaning; the description only reinforces the kind="document" case with concrete examples. It adds no encoding detail, default behavior, or filename semantics beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb and resource — attaches a photo or a document (receipt, manual, warranty card) to an item that already exists — and explicitly contrasts with add_item_from_photo for creating a new thing. An agent can distinguish it from the creation sibling without opening either schema.

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

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

Gives an explicit alternative for the adjacent intent ("To add a new thing from its photo use add_item_from_photo instead") and lays out the downstream workflow: wait ~20s, read results via get_item, confirm with the person, then apply with update_item. The when-to-use and what-happens-next path is fully spelled out.

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 write-but-not-destructive, non-open-world behavior, and the description usefully adds the one thing annotations cannot: it returns the new provider with its id, which matters since no output schema exists. Beyond that it says nothing about required vs optional fields, validation failures (e.g. malformed email), or whether duplicate names are rejected — with only 'name' required and seven optional fields, silence on which fields the tool will accept as empty is a real gap.

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

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

Three short sentences, front-loaded with what the tool creates, followed by the dedup prerequisite and the return contract. Every clause earns its place; no restatement of the title 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?

For an eight-parameter creation tool with no output schema, the description covers the missing piece — the returned id — along with the dedup check and where that id gets consumed. Combined with 100% schema coverage, an agent has enough to call it correctly without further probing.

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 per-field examples already embedded ('Acme Heating & Air', 'Plumber', 'HVAC'), so the schema does the heavy lifting and baseline 3 applies. The description's 'with their trade and contact details' merely echoes the field set rather than adding format or constraint meaning, and it never notes that only name is mandatory.

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

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

States a specific verb and resource ('Adds a service provider') and immediately grounds the abstraction with concrete examples (plumber, HVAC company, electrician) plus the fields it carries (trade, contact details). It also names its purpose in the wider workflow — so maintenance records can name who does the work — which distinguishes it from create_item or add_maintenance.

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

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

Explicitly tells the agent to call list_providers first to avoid duplicates, then to reuse the returned id as providerId on add_maintenance or complete_maintenance. That is a complete when-to-use, prerequisite, and downstream-consumption chain, with the named alternatives rather than an 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?

Beyond the annotations (readOnly=false, destructive=false), the description discloses the clamping floor ("never goes below 0"), a history side effect ("logs the change in the item's stock history"), and an inventory-state side effect ("moves the item on or off the shopping list"). These side effects are exactly what an agent needs before mutating stock; only the absence of any note about error behavior or idempotency keeps it short of a 5.

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

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

The core operation and sign convention are front-loaded in the first sentence, with usage, side effects, alternative routing, and return value following in a tight sequence. No sentence is redundant or restates structured fields verbatim.

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 supplies the return value ("Returns the new count"), and it covers side effects and the sibling alternative for a three-parameter mutation tool. The only gap is that it doesn't say what happens on an unknown id or a delta that would push below zero (clamped vs. error), which slightly matters for an agent planning a call.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a natural-language-to-value mapping example that the schema does not provide, helping the agent translate conversational input into the correct delta sign. The optional `note` parameter is left to the schema, which already documents it adequately.

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?

"Counts consumables up or down" states a specific verb and resource, and the negative/positive delta semantics with a concrete example ("we used the last AA pack" → -1) make the operation unambiguous. It also explicitly separates itself from update_item's exact-count behavior, so an agent can pick correctly without opening either schema.

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

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

"Use it whenever the person uses up or buys something tracked" gives a clear activation condition, and "To set an exact count (after a recount), use update_item's quantity" names the alternative plus the condition that selects it. Both when-to-use and when-not-to-use are covered with no inference required.

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

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

Annotations only cover readOnlyHint and openWorldHint; the description adds genuinely useful behavior beyond them — a prerequisite (AI switched on), a cost model (counts as one AI action), a latency warning (several seconds), and the fact that the answer cites the items it used. Those are exactly the facts an agent needs to decide whether the call is worth making and how to present results.

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

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

One tight paragraph: purpose first, examples second, sibling exclusion third, operational caveats last. No sentence is redundant, and the most decision-relevant content (what it does, when not to use it) 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?

There is no output schema, and the description covers the return shape well enough — a natural-language answer with citations of the items used. With only one parameter and a short prerequisite/cost note, nothing an agent needs in order 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% for the single parameter, so the baseline is 3. The description adds meaning by showing the question is posed in natural language as the person asked it (not keyword fragments), illustrated with two realistic phrasings, which guides the agent's input formatting beyond the schema.

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

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

The description states a specific verb and resource — answering a question in words from the household's own items and documents — and immediately concretizes it with two example questions (warranty end date, furnace filter). It explicitly contrasts itself with search_inventory, so an agent can distinguish the two without opening either schema.

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

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

It names the alternative (search_inventory) and the exact condition that selects it: the person wants to find a thing rather than learn a fact. It also states a prerequisite (the server's AI must be switched on), so the agent knows when the call will not work at all.

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

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

Goes well beyond the annotations by disclosing side effects and state transitions: crediting to the task's usual provider, providerId=null meaning the household did it, the part being decremented from stock, repeating tasks rescheduling one interval after doneOn, one-off tasks being closed out, and reading-based rescheduling by usageEvery. It also states what is returned, which the annotations do not cover.

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

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

Front-loaded with the trigger, then side effects, then the use-based special case, then the return value — a logical order with no filler. It is a single dense block, though, and could be split for faster scanning of the reading/providerId branches.

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

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

For a 7-parameter mutation with no output schema, the description covers the trigger, the id source, provider crediting, stock consumption, rescheduling rules for both recurring and one-off tasks, the usage-based path, and the return value. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning: reading pairs with usageEvery to compute the next due date, providerId's null has a specific household semantic, and usePart's false case is motivated ('an old one was cleaned instead'). Most individual parameter phrasing still mirrors the schema, so it is not a full 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?

States a specific verb and resource ('Records that a task was done') plus the scope of what can be supplied (today or doneOn, note, cost). It is clearly distinguished from add_maintenance, delete_maintenance, and list_maintenance, the latter named explicitly as the source of the 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?

Gives a concrete trigger with a natural-language example ('whenever the person says they did one — "changed the furnace filter"') and routes the agent to list_maintenance for the id. It also carves out the use-based case via reading, but never distinguishes this tool from the sibling record_reading, which an agent could plausibly pick instead when a counter value is involved.

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 a safe read (readOnlyHint=true, openWorldHint=false) and the description does not contradict them. Beyond that it adds real behavioral context: limits live in the app rather than being passed in, amounts are in cents (so values are minor units, not dollars), and the result is empty when no limits are configured — an important edge case an agent would otherwise misread as an error.

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

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

A single dense paragraph that front-loads the core action and its output shape before the disambiguation and the edge-case note. Some nested parentheticals make the middle clause heavy, but every sentence carries information — 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?

No parameters and no output schema, so the description carries the burden of explaining what comes back, which it does (per-limit comparison, shortfall, unvalued-item count). Coverage is good for a zero-arg read tool; only fine details of the result structure are left implicit.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline is a 4. The note that amounts are in cents is the only "input-like" detail, and it is present.

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

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

States a specific verb+resource: checks the household's insurance limits (contents cover, category/tag limits like jewelry or firearms) against inventory values. It names the exact outputs produced (limit vs. worth, shortfall, count of items with no recorded value), which makes it unmistakable against siblings such as inventory_report.

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

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

Gives an explicit trigger phrase ("are we insured enough?") and explicitly routes the alternative case — total worth by room or property — to inventory_report. It also notes the precondition that limits must be set in the app, which explains when the tool legitimately returns nothing.

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 this is a non-read-only, non-destructive write, so the safety profile is covered. The description adds real behavioral context beyond them: new tag names are created implicitly, collectionId seeds fields from a template, wanted items are excluded from totals/report/stock/search, and the new item with its id is returned. It stops short of error/failure behavior or what happens on a duplicate name.

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

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

Front-loaded with the core action and the dedup rule, then grouped by concern (placement, categorization, pricing, collection/wanted, photo path, return value). It is dense and semi-colon heavy, but nearly every clause carries a distinct decision-relevant fact; a small amount of parenthetical tool-name repetition could be trimmed.

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

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

For a 31-parameter creation tool with no output schema this covers what an agent most needs: the one required field, dedup avoidance, the id-lookup prerequisites, the wanted/owned lifecycle, and a stated return value. Remaining gaps are minor because the schema itself documents the long-tail fields (serialNumber, disposition, purchaseDate) thoroughly.

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

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

Schema coverage is 100% and each parameter already carries a rich description, so the baseline is 3. The description does add routing value the schema lacks — telling the agent which sibling tool to call to obtain locationId, categoryId, collectionId and tag context, and reinforcing that prices are in cents and that new tags are auto-created — but it does not explain most of the 31 parameters itself.

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

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

Opens with a specific verb+resource ('Adds a new item') and immediately frames it against siblings (search_inventory, update_item, adjust_stock, add_item_from_photo). An agent can tell exactly which of the ~39 tools this is and which it is not.

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

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

Explicit when-to-use logic with named alternatives: search first to avoid duplicates, update_item/adjust_stock if it exists, add_item_from_photo for photo origin. Also states the wanted:true → update_item with wanted:false lifecycle, which is a non-obvious workflow rule.

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 a non-read-only, non-destructive, closed-world mutation, so the safety profile is covered; the description adds the batch semantics of creating a parent plus children in one call, the propertyId fallback when only one property exists, and the return value (new locations with their ids). It does not mention failure modes, partial-success behavior for batched children, or name-collision handling beyond the list_locations check.

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

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

Front-loaded with the action and the definition of what a location is, then prerequisites, then return value — a sensible order. It is dense and slightly run-on with stacked clauses, but no sentence is filler.

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

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

For a 6-parameter creation tool with no output schema, the description covers the duplicate-prevention workflow, the property scoping fallback, the batch-children case, the sibling tool split, and what is returned. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns an extra point by showing how name and children compose in a single call ("a garage with three shelves") and by restating the parentId nesting intent with a concrete room/shelf analogy. Those composite examples add meaning the per-field schema strings do not convey.

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

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

States a specific verb and resource ("Adds a location") and immediately narrows scope to rooms/closets/shelves belonging to a property. It distinguishes itself from create_property ("a new property itself is create_property") and list_locations, so an agent can pick it out of a crowded sibling list without opening the schema.

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

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

Gives explicit pre-call guidance ("Check list_locations first so you don't add one twice") and an explicit exclusion pointing at the sibling tool for the adjacent task (create_property). It also resolves the common ambiguity of when propertyId is required.

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

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

Annotations already establish readOnly=false, destructive=false and openWorld=false, so the description's added value is what it discloses beyond that: only name is required, type silently defaults to home, the address is optional and only feeds a map picture, and the call returns the new property with its id. It stops short of noting validation failures or duplicate-name behavior, which keeps it off a 5.

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

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

Four short sentences, each doing distinct work: identity, minimum viable call, prerequisite check, sibling hand-off, and return shape. The most decision-relevant constraints (only name required, check list_locations first) are placed early with no filler.

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

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

With no output schema, the description usefully states the return value ('the new property with its id'), and the 10-parameter surface is covered by a fully documented schema. Complete enough to call correctly; the only missing piece is how duplicates or invalid inputs surface as errors.

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 ten fields, including the type default and the map-picture note on street. The description restates the required/default facts rather than adding new semantics such as valueCents units or yearBuilt bounds. Baseline 3 applies when the schema carries the load.

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?

A specific verb ('Adds') plus a precisely scoped resource ('a property — a home, vacation home, rental, storage unit or vehicle'), plus a positional framing ('the top level of where things are kept') that separates it from create_location, which handles rooms/closets/shelves inside it. An agent can distinguish it from every sibling without opening a schema.

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

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

Explicitly routes the agent: check list_locations first to avoid duplicates, and use create_location next for the contents inside the property. It names the alternatives and the ordering condition, which is exactly the when/when-not guidance a creation tool needs.

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

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

Annotations already declare destructiveHint=true, but the description adds the details that actually matter: it is a soft delete held in Recently deleted for 30 days, then becomes permanent along with photos and documents. It also adds an operational precondition ("Confirm with the person first") that no annotation conveys.

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

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

Front-loaded with the action, then the exclusion rule, then the retention/permanence consequence, then the confirmation. Four sentences, each carrying distinct decision-relevant information with no restatement of the title or annotations.

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

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

For a one-parameter destructive tool with no output schema, the description covers everything an agent needs: irreversibility timeline, what data is destroyed, the undo tool, the safer alternative, and the human-confirmation requirement. Nothing material 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?

With one parameter at 100% schema coverage, the schema already documents the id field and even its provenance ("from search_inventory"). The description never mentions the id or any format expectation, so it adds nothing beyond the schema — baseline 3.

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?

Names a specific verb and resource ("Removes an item from the inventory") and immediately scopes it against siblings by naming update_item with disposition and restore_item. An agent can distinguish this from delete_maintenance, restore_item, and recently_deleted without opening any schema.

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

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

Gives explicit when-to-use ("added by mistake or the person wants it gone from the records") and an explicit when-not with the correct alternative ("For something sold, given away, thrown out, lost or stolen, prefer update_item with disposition"). It also names restore_item as the recovery path, so the agent has both a routing rule and a fallback.

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

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

Annotations already flag destructiveHint=true, and the description goes well beyond them: it states the side effects (stops coming due, removes reminders), what is preserved (past completions remain in item history), what is unrecoverable (the task can't be brought back with these tools), and adds a procedural safeguard ('Confirm with the person first'). That is exactly the kind of consequence disclosure a destructive operation needs.

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

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

Three sentences, each doing distinct work: purpose, the wrong-tool exclusion with the correct redirect, then consequences and the confirmation prompt. The key routing information comes first and nothing is padded.

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

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

For a one-parameter destructive tool with no output schema, this covers use cases, alternatives, irreversibility, and side effects. Only minor omissions remain, such as whether recently_deleted offers any recovery path, but an agent has enough to invoke it correctly and safely.

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

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

Schema coverage is 100% and the single parameter is already documented as 'The task's id, from list_maintenance'. The description adds no further syntax or sourcing detail beyond what the schema provides, 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 names a specific verb and resource ('Deletes a maintenance task') and immediately scopes it to the cases that justify deletion (item gone, added by mistake), which separates it from sibling tools like complete_maintenance. An agent can distinguish it from list_maintenance or complete_maintenance without opening a schema.

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

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

It gives an explicit when-not rule — 'This is not for a task that was just done — use complete_maintenance, which schedules the next one' — and describes the legitimate use cases (item gone, added by mistake). The only gap is that it doesn't mention recently_deleted or restore paths as an alternative, but the primary routing decision is fully covered.

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

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

Annotations already flag this as a non-read-only, non-destructive, closed-world write, so the description's job is lighter. It still adds real value by disclosing defaulting behavior (status defaults to filed, filedOn defaults to today) and the downstream consequence that stale claims surface in what_needs_attention. It doesn't say anything about the returned record, which leaves a small 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, front-loaded with the what, then the when, then the follow-up path. No filler and the essential prerequisite is placed before the alternative-tool reference.

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

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

For a nine-parameter creation tool with no output schema, the description covers required fields, defaults, provenance of the warrantyId, and the lifecycle handoff to update_warranty_claim. It is nearly complete, though it never mentions that closure fields (resolution, resolvedOn) can also be supplied at creation time.

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 schema description coverage at 100%, the schema already documents all nine parameters. The description goes slightly beyond it by stating the status and filedOn defaults, which the schema does not spell out for status, so it is a baseline-level contribution rather than a strong one.

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: "Records a claim made under one of an item's warranties," and enumerates the core payload (problem, reference, status). It is clearly distinguishable from update_warranty_claim, which is named separately as the follow-up path.

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 names the trigger condition ("when the person says they've contacted the maker or seller about a fault"), the prerequisite ("get the warrantyId from get_item"), and the alternative for later changes ("Follow it up later with update_warranty_claim"). That covers when, how to prepare, and what to use instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value beyond them by disclosing the breadth of the response, including derived content (what the vision model read in photos) and unconfirmed state ('suggested fields waiting for the person to confirm'), which an agent needs to interpret results. It does not mention pagination or size limits, but for a single-item read that is minor.

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

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

Front-loaded with the core statement, then a second sentence that handles routing to alternatives. Dense but every clause carries information; the enumeration of payload types is long yet each item is distinct.

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 has to convey return values, and it does so thoroughly, including derived vision-model text and pending suggestions that would otherwise surprise an agent. For a one-parameter read-only tool this leaves nothing essential unspecified.

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

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

Schema description coverage is 100% and there is only one parameter, whose provenance ('from search_inventory or list_items') is already stated in the schema. The description implies a single-item scope but adds no format or constraint detail beyond the schema, so baseline 3 applies.

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

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

Names a specific verb and resource ('Everything about one item') and then enumerates the payload: fields, storage location and box, warranties and claims, photos/documents with vision-model extraction, and pending suggested fields. That distinguishes it clearly from item_history and list_items without opening either schema.

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

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

Gives an explicit entry condition ('after search_inventory or list_items has found the item, when you need the details') and names two alternatives with the conditions that select them: item_history for change over time, list_items for a quick scan of many items.

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

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

Annotations only declare readOnlyHint and openWorldHint=false; the description adds the genuinely non-obvious behaviour: valuation falls back from value to purchase price, is multiplied by quantity, is expressed in cents, and excludes gone and wanted items. Those exclusion and unit rules are exactly what an agent needs to interpret the numbers correctly.

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

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

Two sentences, front-loaded with the purpose and followed by the valuation rules and a routing pointer, with no filler. It is dense — the second sentence packs several rules into one clause chain — but almost every clause carries information an agent would otherwise have to guess.

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 parameters and no output schema, the description carries the full burden and meets it: it enumerates the report's sections (by-property totals, by-room totals, top items, unvalued count) and the arithmetic behind them. An agent could answer questions about the returned numbers without further documentation.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly says nothing about inputs rather than inventing them.

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

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

States a concrete deliverable set: totals by property and by room, the most valuable items, and a count of items with no recorded value. That is specific enough to distinguish it from data-listing siblings like list_items or search_inventory, and it also names coverage_check as the different neighbour.

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

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

Gives an explicit trigger phrase ("what's all our stuff worth?") plus an explicit routing rule: use coverage_check to compare against insurance limits. Both the when-to-use and the when-to-use-something-else cases are covered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds ordering (newest first), the pagination signal ("more is true when there are older ones"), and the shape of each entry (when, what in words, who, how). It does not state permissions or rate-limit behavior, but for a scoped read tool that 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?

Front-loaded with the core statement, then usage, then prerequisite, then return shape — a logical order with no filler. The long parenthetical enumeration of event types is dense but each item earns its place by telling the agent what will appear in the history.

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 return-value burden and does so fully: field-by-field entry structure plus the pagination flag. Combined with the named prerequisite and alternative tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so itemId and limit are already documented with bounds and defaults, which sets the baseline at 3. The description reinforces newest-first ordering and ties the "more" flag to the limit, but adds no new syntax or format detail beyond the schema.

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

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

States a specific verb and resource ("What happened to one item, newest first") and enumerates the event types covered: adds, edits, photos, warranties, maintenance, stock, loans. It also names get_item as the sibling for current state, so the agent can distinguish the two without opening either schema.

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

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

Gives concrete use-case examples ("when did we move the ladder?", "when was the furnace last serviced?"), an explicit exclusion ("for the item as it is now use get_item"), and a prerequisite workflow ("Get the id from search_inventory first"). Nothing about when to reach for this tool is left to inference.

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

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

Annotations only declare write/non-destructive/non-open-world; the description adds real context: the single-open-loan invariant, the fact that reminder emails are configured in the app rather than by this call, and an outline of the returned object. It stops short of saying what happens if a loan is already open or any authorization requirements.

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

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

The purpose comes first, then the trigger example, then the state constraint and follow-up tool, with no wasted framing. The trailing sentence about the return value is slightly garbled ("its id (for loan_returned)") and costs a point of clarity.

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 6-parameter mutation tool with no output schema, the description covers trigger, prerequisite, invariant, and a sketch of the return value. The return-object phrasing is ambiguous and error conditions are unstated, but nothing fatal is missing.

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

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

Schema coverage is 100% and the schema already documents every field including the direction enum and date formats, so the description adds little beyond repeating the itemId provenance. 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 states a specific verb (records a loan) plus the two directional resources (lent vs borrowed) and defines each direction inline, so an agent can distinguish it from siblings like list_loans or item_history without opening the schema.

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

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

It gives an explicit trigger phrase ("I lent the drill to Sam"), a prerequisite workflow step (get the item's id from search_inventory first), a state constraint (one open loan at a time), and names loan_returned as the tool that closes the loan. This is close to a complete when/when-not map.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds the actual return shape, which matters because there is no output schema. It does not mention household size limits, empty-category behavior, or performance, so it falls short of full disclosure but is well above baseline.

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 return contents come first and the call-to-action guidance second, which is the right order. The first sentence is long and parenthetical-heavy, but each clause (categories, tags, templates) earns its place by naming distinct output data.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so for all three result sets including the nested extra-field concept. Missing only edge-case behavior such as empty households or output size, which is minor for a zero-parameter read.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a no-param tool is a 4; nothing here contradicts or omits parameter 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?

Names the three resources returned (categories as a tree, tags with counts, item templates) with concrete detail about what each contains — ids, paths, item counts, extra fields. That level of specificity distinguishes it from sibling lists like list_locations or list_collections without needing the schema.

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

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

Explicitly says to call it before create_item or update_item, and states the three lookups it supplies (categoryId, existing tag names to avoid near-duplicates, templateId) plus the downstream step of placing values in customFields by key. That is a concrete when-to-use trigger tied to named siblings.

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

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

Annotations already declare a safe, non-open-world read, so the description doesn't need to argue safety. It instead adds real behavioral detail: pieces counts duplicates, sums are in cents, and templateId points back to list_categories. Ordering, pagination, or whether zero-count collections appear are not addressed.

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

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

Front-loaded with the resource and what each row contains, then the usage trigger, then the sibling pointer. The heavy parenthetical nesting ('pieces counts duplicates', 'cents') makes it dense but every clause carries information.

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

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

With no output schema and no params, the description carries the return-shape burden and does it well by naming the fields an agent will see. Missing only secondary details like result ordering or inclusion of empty collections, which an agent might need before calling.

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

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

The tool takes no parameters, so there is nothing to disambiguate and the baseline applies. The description uses the space instead to explain output fields rather than inventing parameter guidance.

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

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

States a specific verb and resource ('The household's collections') and immediately enumerates what each entry carries: piece counts, want-list counts, value and cost in cents, and templateId. It also draws the boundary against sibling list_items, which holds the individual things.

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

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

Gives concrete triggers ('how's the coin collection?', getting a collectionId) and names the sibling to use for the underlying things. It stops short of stating exclusions, such as when to prefer inventory_report or list_categories outright, but the routing intent is clear.

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

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

Annotations already flag readOnly/openWorld=false, but the description adds real behavior: default ordering, 50-per-page paging with offset, that the response carries each item's location, and that want-list items are excluded unless wanted='include'/'only'. That is context the annotations do not cover.

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

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

Front-loaded with the core behavior before the filter catalog, and every clause carries information. It is dense and parenthetical-heavy, which makes it slightly harder to scan, but nothing is filler.

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

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

For a 9-parameter read tool with no output schema, it covers ordering, paging, the implicit total, response shape ('with where each is kept') and every filter's scope. An agent has enough to call it correctly on the first attempt.

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%, yet the description still adds meaning the schema lacks: locationId includes nested sub-places, containerItemId is direct contents only, categoryId includes subcategories, tag may act as a collection, and origin='claude' means things the agent itself added. These distinctions change how the filters are chosen.

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 ('Lists') and resource ('items'), plus the ordering ('most recently changed first'), page size and included location data. It explicitly separates itself from search_inventory, so an agent can pick it without opening a schema.

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

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

Gives an explicit routing rule: 'Use it to browse rather than search' and 'To find a particular thing by name, use search_inventory.' Each filter is then framed by the question it answers ('what's in the garage?'), which is stronger than a bare when-to-use statement.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds scope behavior that annotations cannot express: results are limited to open loans, overdue entries are flagged, and each record carries a loanId. It stops short of describing ordering or completeness guarantees, so it is strong but not exhaustive.

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?

Content is front-loaded: the resource and its contents come first, then the usage examples and routing hint, then the scope caveat. The opening sentence is somewhat run-on with stacked parentheticals, but every clause (who has it, since when, due date, loanId) carries real 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?

With no input parameters and no output schema, the description carries the full burden and does so: it describes what fields each record contains, that only open loans appear, and where returned loans can be found. An agent has everything needed to call it and interpret the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and no way for it to under-specify inputs; the baseline 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 names a concrete resource (things lent out and things borrowed), its scope (only open loans, overdue marked), and a distinguishing payload (each with its loanId). It is clearly separable from siblings like item_history and loan_returned, which the text explicitly references.

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 concrete example questions ("who has the ladder?", "what have I lent out?") plus an explicit routing rule: use this to obtain the loanId needed by loan_returned. It also states an exclusion — returned loans live in each item's item_history — so the agent knows when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's 'Read-only' clause is partly redundant. However, 'the whole tree in one call' adds genuinely new behavioral context: the result is complete and unpaginated, so the agent needn't loop or page. It stops short of describing ordering or scale limits, which keeps it from a 5.

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

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

It is short, front-loads the return shape, and every clause carries information (contents, ids, counts, prerequisites, safety). The first sentence is a verbless fragment and 'Read-only' restates an annotation, which are minor blemishes rather than wasted bulk.

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 parameters and no output schema, the description must carry the return shape itself, and it does: properties, nested locations as a tree, ids, and per-location item counts. Combined with the annotations, an agent has everything needed to decide to call it and to use the result.

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

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

The tool takes zero parameters, so there is no parameter meaning for the description to add and the baseline applies. The description correctly implies no filtering arguments are needed to get the full tree.

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 the resource (properties and their locations as a tree: rooms › closets › shelves) and the payload (ids plus item counts per location), which is far more specific than the title 'List places'. An agent can distinguish it from siblings like list_items or list_categories purely from this text.

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 explicit when-to-use routing: call it to obtain a locationId or propertyId before create_item, move_item, list_items or create_location. It also states a second condition — verifying a place exists before adding it again — which covers the duplicate-prevention case and names the concrete downstream tools.

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

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

Annotations already declare readOnlyHint and closed-world behaviour, and the description adds real context beyond them: result ordering, the fields returned per task, and the anti-duplication purpose. It does not mention result limits or how the default status filter narrows the list, so it stops short of fully explaining what an agent will actually receive.

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 efficiently loaded sentence covering purpose, ordering, output fields, and routing, with the parenthetical examples earning their space. The closing clause is a fragment ("for just what's urgent across everything, what_needs_attention"), which reads awkwardly but is still parseable.

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

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

For a two-parameter, no-required-argument read tool with no output schema, the description covers what is returned and why to call it, which is the right level. Only the absence of any note on result size or the default open-only scope keeps it from being 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 coverage is 100% and the enum values are already spelled out with meanings, so the schema carries parameter semantics. The description adds only the soft hint that the default view excludes finished one-offs; it does not explain how status interacts with the ordering or what itemId values to supply beyond the schema's pointer to search_inventory.

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

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

States a concrete resource (maintenance tasks) with examples of what counts (filters, boiler, gutters), the ordering (soonest due first), and the per-row payload (id, item/place, usual assignee). That is enough to distinguish it from what_needs_attention and from generic item listings without opening the schema.

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

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

Gives three explicit use cases (view the schedule, get an id for complete_maintenance, check before add_maintenance to avoid duplicates) and names the alternative for the urgent-everything view. The when-not is implicit in that routing, which is normally enough, and the sibling names are precise.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds real value by disclosing the shape of the returned data (derived aggregates like task counts, visit frequency, and spend). It does not mention ordering, limits, or what an empty household returns, which is a minor gap for a zero-parameter read.

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

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

Two sentences, front-loaded with what the tool returns before the usage scenarios. The first sentence is a long comma-separated run, but every clause (contacts, counts, frequency, last visit, spend) describes a distinct useful output field, so little is wasted.

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

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

There is no output schema, and the description compensates by enumerating the returned fields. Combined with the explicit providerId dependency on add_maintenance/complete_maintenance and the duplicate-check role before add_provider, an agent has everything needed to call this correctly.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline for a zero-param tool is 4. The description correctly spends no words on inputs and instead explains the output.

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?

Names a specific resource (the household's service providers) and enumerates exactly what the listing contains: contact details, task counts, visit frequency, last visit, and spend. An agent knows this is the provider roster, distinct from list_maintenance or list_items, without opening any schema.

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

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

Gives three concrete invocation triggers: answering 'who did we use for the furnace?', obtaining a providerId required by add_maintenance/complete_maintenance, and pre-checking before add_provider to avoid duplicates. It explicitly routes the agent to sibling tools and states the dependency relationship rather than leaving it to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds genuinely new behavioral facts: results are sorted soonest-expiry-first and each result carries id, item, provider, dates and status. It does not mention pagination or result limits, which is the remaining gap for a list tool.

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

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

Two sentences, front-loaded with the resource and ordering, then the return fields, then the routing guidance. The parenthetical '(status expiring)' is a compact, useful pointer; no sentence is decorative.

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

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

For a single optional enum parameter with full schema coverage and no output schema, the description covers scope, ordering, response fields, and sibling routing. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the enum definitions are already documented; the description still adds value by mapping a natural-language intent ('what's about to run out?') to the specific 'expiring' value, telling the agent which filter to choose rather than just what it means.

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

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

States a specific verb+resource ('Warranties on file across all items'), plus the sort order ('soonest to end first') and the exact fields returned. It also explicitly distinguishes itself from get_item and what_needs_attention, so an agent can pick it without opening the schema.

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

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

Gives concrete triggering questions ('what's still under warranty?', 'what's about to run out?'), points to the 'expiring' status for the second case, and names two alternatives with the conditions that select them (get_item for a single item's warranties and claims, what_needs_attention for urgent items in a combined view).

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?

Above the annotations (which only say it is a non-destructive write), the description discloses the side effects an agent cannot infer: the loan is retained in the item's history, the borrower's reminder emails stop, and nothing else about the item changes. It also warns that a repeated call for the same loan is refused because it is already back, which prevents a common retry error.

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

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

Three short sentences: purpose first, then when to use, then consequences. Nothing is padded, and the most decision-relevant framing leads the 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 two-parameter mutation with no output schema, the description covers preconditions, side effects, and the idempotency refusal, which is nearly everything an agent needs. The only gap is that it does not indicate what the call returns on success, leaving the agent to infer the response shape.

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

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

Schema description coverage is 100%, so both loanId and the optional 'on' date are already documented, and the description's note that loanId comes from list_loans merely restates the schema. The 'on' parameter (default today, yyyy-mm-dd) is not mentioned at all, so the description adds little beyond the schema 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?

'Closes a loan: a lent thing is back, or a borrowed one was given back' gives a specific verb (closes) and resource (loan) and covers both directional cases. It is immediately distinguishable from the sibling lend_item, which performs the opposite transition.

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 states the triggering condition with a concrete example ('Use it when the person says so ("Sam returned the ladder")') and points to list_loans as the source of the loanId, which is real routing guidance. It also gives a when-not via the repeat-call refusal, though it never names an alternative for correcting a mistaken return.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds real substance beyond them — the two-tier lookup order (local barcode book first, online product database only 'if it's switched on') and the null-match case when the code is unknown. It does not cover latency or failure behavior for the external lookup, which is the remaining gap given the open-world hint.

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?

Information is front-loaded: purpose, then when-to-use, then lookup mechanics, then return shape, then follow-up behavior. Every sentence carries useful content, though the final adjust_stock sentence is dense and could be trimmed slightly without losing meaning.

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 supplies the return contract itself (match with name/brand/model/source/photos, null when unknown; youHave with id/name/quantity/place). For a single-parameter read-only tool, nothing an agent needs to call it or interpret the result is missing.

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

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

Schema coverage is 100% and the schema already explains the parameter as the digits for UPC-A/EAN-13/EAN-8, so the description's 'UPC/EAN barcode' phrasing adds little. Baseline 3 applies since the schema carries the parameter burden, including the 8-20 character constraint that the description never mentions.

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 sentence names a specific verb and resource ('Says what product a UPC/EAN barcode is') and adds the household-possession angle, which uniquely identifies this tool. It also explicitly contrasts with search_inventory ('to find a thing by name'), so an agent can separate it from siblings without reading schemas.

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

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

It states the triggering situation ('when the person reads out or scans a barcode'), the ordering relative to another tool ('before create_item'), and the alternative for a different intent ('to find a thing by name use search_inventory'). It even routes the follow-up decision: prefer adjust_stock over a duplicate when youHave is non-empty.

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

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

Annotations only say it is a non-read-only, idempotent, non-destructive write; the description adds the cascade semantics that matter operationally: moving a box carries its contents, moving a contained item removes it from that box, and the change is logged in item_history. Those side effects are absent from the annotations and 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?

Front-loaded with the core action and then the containment exception; the conversational example earns its place because it disambiguates the containment edge case. Slightly loose phrasing ("nowhere in particular" repeated) but no wasted bulk.

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

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

For a two-parameter mutation with no output schema, the description covers cascade behavior, the box alternative, and the audit trail. It does not say what happens on an invalid or deleted locationId, which is the main residual gap.

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

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

Schema coverage is 100% and both parameters already document their source tools (search_inventory, list_locations) and the null meaning. The description restates the same locationId semantics nearly verbatim, adding little beyond the schema.

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

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

States a specific verb+resource: it records that an item now lives at a new location, and explicitly contrasts with put-something-into-a-box (update_item). An agent can distinguish it from update_item and adjust_stock without opening the schema.

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

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

Gives a concrete colloquial trigger ("I put the drill in the basement") and names the sibling plus its parameter to use instead when the intent is containment. When-to-use and when-to-use-something-else are both explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description then adds real substance beyond them — a 30-day retention window, newest-first ordering, the presence of a deleter identity and a purge date per record, and the scope boundary. It stops short of saying whether the list is paginated or capped, which matters for a bulk read.

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 load-bearing: the first defines the result set and ordering, the second gives the usage trigger and sibling handoff, the third sets the exclusion boundary. The identifying information (30-day window, newest first) is front-loaded, and phrasing like 'the day each goes for good' conveys the purge date compactly.

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 zero-parameter read with no output schema, so the description carries the burden of describing what comes back, and it does: ordering, deleter attribution, purge timing, and scope. Nothing an agent needs in order to decide to call it or to interpret the result is missing.

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

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

The tool takes no parameters, so there is no schema surface for the description to clarify and the baseline of 4 applies. The description wisely spends its words on output shape and scope instead of inventing parameter guidance that does not exist.

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

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

The description gives a specific verb-resource pair and adds the defining scope: items deleted within the last 30 days, ordered newest first, annotated with deleter and scheduled purge date. It also explicitly carves out what is NOT included (deleted maintenance tasks, places), which lets an agent separate it from list_maintenance and list_locations at a glance.

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 names the triggering user intents (wants something back, asks what was removed) and routes to the correct follow-up tool by name: restore_item, with the note that it works by id. The explicit 'only items' exclusion tells the agent when to look elsewhere, so both the when and the when-not are covered.

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

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

Annotations only declare this is a non-destructive write within a closed world; the description adds the real side effect — usage-based maintenance ("every 5,000 miles") is rescheduled from the reading — plus the prerequisite that the item must already have a usageUnit. It stops short of covering edge cases such as a reading lower than the previous one or what happens if usageUnit is missing.

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 tight sentences: what it does, what it affects downstream, then when to use it versus the alternative. The verb and the routing constraint are front-loaded, and the unit examples earn their space by preventing unit confusion.

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

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

For a four-parameter write tool with no output schema, the description covers purpose, prerequisite, side effect, and sibling routing. Only minor gaps remain — no mention of validation behavior for decreasing readings or the response shape after logging.

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 genuine value by enumerating the possible unit values (miles, km, hours, cycles) that the schema leaves as an open string, and by tying `value` to the item's configured unit rather than a free-form number.

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

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

States a specific verb and resource ("Records what an item's counter says now") and anchors it with concrete instances (car odometer, mower/generator engine hours, furnace run hours). It is clearly distinguishable from sibling write tools like update_item or complete_maintenance.

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

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

Gives an explicit positive trigger ("Use it when the person mentions a reading") and an explicit alternative with its condition ("when they've just done the maintenance, give the reading to complete_maintenance instead"). It also names the prerequisite tool (update_item) needed to set usageUnit.

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

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

Annotations only convey readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds real behavioral substance on top: the scope of what is restored (attachments and related records), the 30-day recoverability limit, the fallback behavior when the parent location/box no longer exists, and the return payload (restored item's id and name). None of this is derivable from the annotations or schema, and nothing contradicts them — restoring is consistent with a non-destructive write.

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

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

Three short sentences that are front-loaded with the action and source, followed by a usage condition, then the edge case and return value. Every sentence carries distinct information with no repetition of the tool name or schema.

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

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

For a single-parameter mutation with no output schema, the definition covers what the agent otherwise could not know: the 30-day recovery limit, what related data comes back, the degraded-restore case, the follow-up tool, and the shape of the response. Nothing needed to call or interpret this tool correctly appears to be missing.

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

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

Schema coverage is 100% and the single parameter is already documented as 'The deleted item's id, from recently_deleted', so the description's mention of the same source adds only minor reinforcement. With one fully-described parameter, the baseline of 3 is correct; the description does not add new syntax or format guidance beyond the schema.

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

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

States a specific verb and resource ('Brings back an item from Recently deleted') and immediately names the data source ('ids from recently_deleted'). It also enumerates what the restore carries with it (photos, documents, warranties, maintenance) and names the sibling (move_item) that handles the related follow-up, so an agent can distinguish it from delete_item or move_item without opening any schema.

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

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

Gives an explicit when-to-use condition ('when the person wants a deleted thing back within 30 days') plus a hard constraint (the 30-day window). It also handles the notable edge case — the item's place or box being removed meanwhile — and routes the agent to move_item for that follow-up, which is exactly the alternative-selection guidance an agent needs.

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 readOnly and openWorld annotations, the description explains each status's meaning, what a ready result contains, what to do with the person's choice, and what happens when scanId is omitted. This is rich behavioral context for a read-only 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 definition is front-loaded and every clause serves a purpose, but the single dense paragraph with inline parentheticals and semicolons is somewhat run-on. It could be structured more cleanly without losing content.

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 does well to enumerate statuses and describe the ready and done payloads. It does not elaborate on the failed status or return formatting, leaving a minor gap for a tool whose results are the primary output.

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

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

Schema coverage is 100%, so the schema already documents scanId and its omitted behavior. The description usefully ties scanId back to scan_room or the app, but does not add syntax or constraints 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 and resource, 'Checks on a room scan', and immediately clarifies the possible statuses. It also distinguishes the tool from scan_room and add_from_room_scan by naming both and describing the workflow.

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

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

It explicitly says to use this for scans from scan_room or the app, gives polling guidance for pending scans, explains that omitting scanId returns every unfinished scan, and points to add_from_room_scan once the person has chosen.

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

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

Annotations only say this is non-destructive and closed-world; the description adds what they cannot: it runs in the background (20–60 seconds), results land in room_scan_results, nothing is written until the person confirms via add_from_room_scan, and each photo costs one AI action. That staged-write semantics and latency/cost disclosure is exactly the context an agent needs before calling.

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

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

Front-loads what it finds, then usage, then where to point it, then the async/confirmation contract — each sentence carries distinct operational information with no filler. Length is justified by the async workflow it must convey.

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 an async, side-effect-deferred AI tool with no output schema, the description covers timing, where results appear, what is not yet persisted, and the confirmation path. Nothing needed to call it correctly or to avoid a premature write is missing.

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

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

Schema coverage is 100% and the schema already documents photos as base64, the 1–5 bound, locationId from list_locations, and containerItemId as 'Or the box'. The description mostly restates that with 'Say where with locationId (a room) or containerItemId (a box)', adding framing but little new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Finds the things worth inventorying in 1–5 photos of a room or an open box') and even names the downstream output shape (name, category, count). It explicitly separates itself from the sibling add_item_from_photo, so an agent can choose without opening either schema.

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

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

Gives the selecting condition ('when the person wants to add a lot at once') and the alternative for the opposite case ('for one thing use add_item_from_photo'). It also names the required follow-up (add_from_room_scan) and the results tool, so the whole workflow is routable from the description alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds substantive behavioral context: semantic matching, best-match ordering, QR-label lookup, and exclusion of gone or wanted-only items. It also describes the return shape, including each item's id, fields, location path, and what matched.

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 search behavior and then routes to alternatives. It is dense and uses several parenthetical examples, but every sentence carries useful information. Minor tightening would improve readability without losing content.

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, yet the description explains the return value well enough: items with id, fields, location path, and match information. It also covers key behavioral constraints and alternatives, making it complete for this search tool.

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

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

Schema description coverage is 100%, so the baseline is 3 even though the description does not walk through parameters. The description adds some query semantics, such as names, brands, serial numbers, receipt text, and natural-language meaning, but most of this overlaps the schema's own examples. The limit parameter is left entirely to the schema.

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

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

The description states a specific verb and resource: finds inventory items by words or meaning, with best matches first and location included. It also distinguishes special behavior like a box's 6-character QR label code. An agent can tell exactly what this tool does without inspecting the schema.

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

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

It explicitly says to start here whenever the person mentions a thing, to answer 'where is…', and before create_item to avoid duplicates. It also names alternatives for document questions (ask_inventory) and browsing (list_items). The when-to-use and when-not-to-use routing is complete.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds useful behavioral context by defining the inclusion rule (run out or at/below minQuantity) and the returned information (remaining count and suggested buy amount). It also implies run-out-first ordering, though it does not go further into formatting or sorting details, which is acceptable 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 appropriately short and front-loads the core concept ('What to buy, run-out first') before explaining criteria and usage. The final 'Read-only' repeats an annotation already supplied, but the overall structure is efficient and easy to scan.

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

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

With no input parameters, no output schema, and annotations covering read-only/open-world behavior, the description provides everything needed: what is included, what the results contain, and how to follow up after purchasing. No material gap remains for an agent selecting and invoking this tool.

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

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

The tool takes no input parameters, so there are no parameter semantics to clarify. The mention of minQuantity provides helpful meaning about the underlying inventory field even though it is not an input to this 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 states a specific resource and scope: tracked consumables that have run out or are at/below their minimum, with remaining quantity and a suggested purchase amount. It distinguishes the tool from broader list/search siblings by its run-out filter and explicitly points to adjust_stock for the post-purchase update.

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 explicit usage contexts: answering 'what do we need?' and checking before a shop. It also names the alternative action after buying, adjust_stock with a positive delta, making the when/when-not boundary 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 non-read-only, non-destructive, idempotent, closed-world, so the safety bar is partly met. The description still adds the two behaviors that matter most for a partial update: omitted fields are preserved and null clears a field, plus the footgun that tags and links replace the entire list rather than merging. Only the return payload is treated shallowly ("Returns the updated item").

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

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

Front-loaded with the core action, then the update rules, then the sibling routing, then the return. Every sentence carries a distinct rule. The only waste is the trailing ellipsis in the field list, which signals incompleteness without adding 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 31-parameter mutation tool this is close to sufficient: the agent knows how updates are applied, how to clear values, which values replace whole lists, when to prefer a sibling, and that it gets the item back. Minor gaps are unaddressed interactions (for example setting disposition alongside quantity or containerItemId side effects), but those are individually documented in 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?

Schema coverage is 100%, so the baseline is 3 and per-field meanings are already documented. The description goes beyond that with cross-field update semantics that no individual property description carries: omit-to-keep, null-to-clear, and full-list replacement for the two collection-valued fields.

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

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

Opens with a specific verb and resource ("Changes some of an item's fields") and immediately enumerates the field families so the agent knows the surface area. It also names the counterpart tool get_item as the source of confirmed suggestions, making it distinguishable from siblings without opening a schema.

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

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

Explicitly routes three adjacent intents away: move_item for relocation, adjust_stock for count changes because it logs them, and record_reading for counter values. It also states the precondition (the person has said what to change), which is the when-to-use condition rather than just a when-not.

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 safe-read=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds genuinely new behavior: partial-update semantics ("Fields left out stay as they are") and a side effect not in the schema — closing a claim stamps today's date unless resolvedOn is supplied.

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

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

Three short sentences ordered well: what changes, when to use it, then the non-obvious dating rule. Tight overall, though the field list ("what it cost (cents), the claim number") is a partial restatement of what the schema already names.

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

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

For a nine-parameter mutation tool with no output schema, the description covers the trigger, the update semantics, and the one hidden side effect; remaining field meanings sit in a fully-covered schema. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters, making 3 the baseline. The description does add one piece of meaning the schema lacks — the status/resolvedOn defaulting interaction — but it omits notes, problem, and filedOn and mostly restates field meanings already 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?

Opens with a specific verb and resource ("Changes a warranty claim") and enumerates the mutable fields: status, resolution, cost, claim number. An agent can tell this apart from file_warranty_claim from the name plus the field list, though the sibling is never named explicitly.

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?

"Use it when the person hears back about a claim" gives a concrete trigger condition, and "the claim's id is in get_item" routes the agent to the right source for the required parameter. No explicit when-not guidance or named alternative (e.g., file_warranty_claim for new claims) is provided.

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 read-only and closed-world annotations, it discloses urgent-first ordering, concrete time windows for several alert types, the two severity values, result fields, and the empty-result case. These details set useful expectations about aggregation and output behavior, and nothing conflicts 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?

Purpose and urgency are front-loaded, followed logically by result shape, usage routing, and empty behavior. The category list and sibling-routing sentence are dense, making the paragraph somewhat long, but nearly all of the wording earns its place.

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

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

For a zero-parameter aggregator without an output schema, it supplies the inclusion rules, ordering, result fields, severity values, empty state, and boundaries with neighboring tools needed for correct use. A few categories such as things running low lack precise thresholds, but that does not create a material selection or invocation 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 tool has no parameters, so there is no argument syntax or meaning for the description to clarify; the zero-parameter baseline applies. It appropriately focuses on selection criteria and result behavior rather than adding unnecessary parameter guidance.

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 sentence defines an urgent-first queue of actionable issues and enumerates its maintenance, warranty, claim, stock, loan, recall, insurance, and photo-scan sources. The later references to list_maintenance, list_warranties, and shopping_list further distinguish its aggregated, attention-only scope from those narrower 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?

It explicitly recommends the tool for broad questions such as "anything I should deal with?" and for a daily check-in. It also routes full maintenance schedules, comprehensive warranty views, and purchasing needs to list_maintenance, list_warranties, and shopping_list respectively.

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