TerraVault

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

The description adds substantial behavioral detail beyond the annotations: it defines the four possible outcomes, explains that RECALLED requires an exact match, clarifies SOLD_RECALLED_PRODUCT for stores that sold recalled products, includes the list-read date for NOT_IN_INDEX, and explicitly warns that it never says a product is safe.

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

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

The description is three tight sentences with no filler. It front-loads the core purpose, then input modes, then output semantics and scope. Every sentence contributes useful information.

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

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

Given the tool's complexity, four optional parameters, no output schema, and read-only annotations, the description is complete enough to use correctly. The possible outputs are enumerated, the exact-match rule is clear, and the California-only scope and safety caveat are stated.

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 each parameter. The description still adds value by describing the accepted invocation combinations, especially that a batch number should be supplied with its maker, and by connecting inputs to exact-match recall semantics.

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

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

The description states a specific verb and resource: checking a cannabis package or license against California's cannabis recall list. It also scopes the tool to California only and distinguishes its recall-specific purpose from general license lookup tools, so an agent can identify 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?

It clearly explains the accepted input modes: package UID, batch number with maker, or license number. The California-only constraint is explicit, but it does not name sibling tools or explicitly say when to use this instead of lookup_license or licensed_near.

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 read-only, idempotent, closed-world behavior, so the description's job is to add context, and it does: nearest-first ordering, each result carrying its distance plus how the distance was measured, and the caveat that licensing does not imply the store is open or stocked. The 'maker' result kind is explained, though the schema's kind enum does not include 'maker', which leaves a small ambiguity about whether that is a request filter or only a result label.

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

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

Four short sentences, front-loaded with the core operation and scope, followed by result shape, the maker edge case, and the licensing caveat. Nothing is redundant, though the 'maker' sentence is narrow for its position in an otherwise general 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?

With no output schema, the description must carry the return-shape burden, and it partially does (distance, how it was measured, TerraVault page, maker kind). However, for a 6-parameter tool it omits what miles and limit do, and gives no sense of result volume or whether an empty radius result is possible.

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 50%, and the description covers zip, city, state, and the result-kind concept, but says nothing about miles (radius options 10/25/50) or limit (1-25 results), the two parameters whose meaning and defaults are least self-evident. Baseline 3 is appropriate given the partial schema documentation it complements.

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 (find licensed cannabis stores and delivery services near a place), the data source (the state's own license lists), and the ordering (nearest first). That geographic-proximity framing distinguishes it clearly from siblings like lookup_license, state_license_counts, and state_license_report, which operate on individual licenses or aggregate views.

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?

Tells the agent the two supported lookup modes (ZIP, or city in a given state) and implies the state parameter is required with city via the schema. It also warns that a license does not mean a store is open or stocks an item, which sets expectations about the result. It stops short of naming a sibling for a specific-license lookup.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context on top: the returned fields (license type, status as printed, city/county, list read date, state record link) and an explicit privacy boundary ('Never returns phone numbers, emails or owner details'). The freshness signal ('date the list was read') is exactly the kind of trait annotations cannot convey.

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

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

Two sentences, front-loaded with the action and lookup keys, followed by the return/coverage detail. The state list is dense but functional; 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?

With no output schema, the description compensates by enumerating the return fields, the geographic coverage, and what is intentionally excluded. An agent has everything needed to call it and to set expectations on results.

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

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

Schema description coverage is 100% and the schema already documents both parameters, including the example license-number format. The description only restates the accepted key types, so it adds no meaning beyond the structured data — 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 ('Look up a cannabis or hemp business license') plus the lookup keys (license number or business name) and the exact state coverage. That scope makes it distinguishable from siblings like state_license_report and licensed_near 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 clear context for use — you have a license number or business name and want the state's own record from TerraVault's covered lists. It does not explicitly name when to prefer licensed_near or state_license_counts instead, so no exclusions are offered.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the data is from TerraVault's own records, every line carries its source and read date, and the window caps at 7 days.

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: identity, payload contents, return behavior. The 'Mary's Desk: TerraVault's short daily update' opening is slightly branded overhead but also establishes the product context, and the payload enumeration comes before the default-handling note.

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, no-output-schema, read-only digest, the description covers what the content is and how much is returned by default. It hints at output shape ('every line names its source and the date it was read'), though it does not say whether the digest is grouped by state or section, which would help an agent parse the response.

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 'days' parameter, so the baseline is 3. The description reinforces it by stating the default (latest day) and the ceiling ('up to the last 7'), clarifying the semantics of magnitude in a way the schema's min/max alone does not convey as naturally.

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 concrete contents: licenses added/removed from state lists since the prior update, new California recalls, and California's month-to-date license report, plus the default lookback. That is a specific verb-and-resource picture, not a restatement of the opaque name 'marys_desk'. It stops short of differentiating from siblings like check_recall or state_license_report, which overlap in subject matter.

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?

Framing it as a 'short daily update' and 'Returns the latest day by default' implies it is the digest entry point rather than a lookup, which is useful implied usage. However, it never says when to prefer this over check_recall for a single recall or state_license_report for a full state list — the agent must infer the routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond them: the data comes from the state's own list, and license links are attached only "where the name matches" — signalling fuzzy matching and that some records will lack a link. Pagination and result limits remain unspecified.

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 front-loaded sentence with the resource first, then the source, then enrichment, then filters and scope. No filler or restated title.

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

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

For a simple two-optional-filter read tool with full annotations and no output schema, this covers source, scope, and the notable link-matching behavior. It stops short of describing the record shape (name, city/county, license link) or result volume, which an agent would want since no output schema exists.

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 are optional, so the schema already carries the semantics. The description restates the filter and adds the value-domain constraint (California only), but says nothing about matching behavior — exact vs partial, case sensitivity, or how city and county combine when both are supplied.

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 (list) and a precisely bounded resource: growers/distributors certified under OCal, California's comparable-to-organic standard. Names the data source (the state's own list) and the enrichment (TerraVault license links), which makes it unmistakably distinct from the general license-lookup siblings such as lookup_license or state_license_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?

"Optional city or county filter. California only." gives usable context and a hard geographic boundary, so when to reach for it is implied. But it never says when not to use it or which sibling to use instead for general license lookups, recalls, or counts.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful domain context: only active licenses are counted, and results include the list's last-read date and publishing agency, which is important for trusting freshness.

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, front-loaded sentence with zero filler. It conveys scope, grouping, and returned metadata without repetition.

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

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

For a one-parameter, read-only tool, the description is nearly complete: it explains what is counted, how it is grouped, and two important returned metadata fields. With no output schema, it could say slightly more about the shape of the returned counts, but the essentials are present.

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

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

Schema coverage is 100% and the single state parameter is fully documented in the schema. The description adds only that the state corresponds to 'one state's list,' but no additional format or validation detail beyond the schema's two-letter code pattern.

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: counting active cannabis licenses on one state's list, broken out by license type. This clearly distinguishes it from lookup_license and licensed_near in practice, though it never names a sibling tool 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?

The use case is strongly implied by 'one state's list, by license type,' but there is no explicit 'use this when' or 'use X instead' guidance relative to state_license_report or lookup_license.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the data provenance ('state's own published list'), the coverage start ('Reports start October 2026'), and the default period ('Defaults to the month in progress'). It does not say what happens for months before the start date or how long a report takes.

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 sentence plus two short clauses; the resource and scope are front-loaded and nothing is redundant. The mid-sentence list ('first seen, left and came back') is slightly compressed but still readable, and the start-date and default notes are placed where the agent will look for them.

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 enumerates the report's fields (start/end counts, first seen, departed, returned) and its breakdown dimensions (license type, county, city), so the agent can judge relevance without a schema. Combined with annotations and the time boundary, nothing needed to select or call the tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and format patterns plus the 2026-10 lower bound are already documented. The description earns a bit more by disclosing the default value for month (current month in progress), which the schema does not state, and by clarifying that state refers to a single state's own list.

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 ('One state's monthly cannabis license report from its own published list') and enumerates the report's contents, so an agent knows exactly what it returns. It does not explicitly distinguish itself from the closest sibling, state_license_counts, which an agent must infer from the endpoint/report framing.

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

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

Usage is implied by 'monthly license report' and the default-to-current-month note, but there is no explicit when-to-use or when-not, and no alternative named among check_recall, state_license_counts, lookup_license, etc. The agent is left to infer that this covers aggregate month-over-month churn while lookup_license handles individual records.

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