Detritus Site Services: Get a Quote

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only' is largely redundant. The description earns credit for genuinely new behavioral context: 'building' is a normal intermediate state, polling should be suppressed via keepPolling, and a sent status yields a quote link and price summary.

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 tight sentences with no filler: identity and states first, prerequisites second, polling behavior third, return content last. Information is front-loaded in the order an agent needs it.

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?

An output schema exists, so return values need not be enumerated, yet the description still flags the one case that matters (sent returns the quote link and price summary). Combined with the state enumeration and polling rule, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: although only serviceRequestId is marked required, the description tells the agent that phone or email must also be supplied to authenticate the lookup. It does not explain the preferred-phone rule that the schema itself carries.

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 ('Get the status of an existing Detritus quote request') and enumerates the possible states (received, assigned, building, sent), which pins down exactly what is returned. It is easily distinguished from siblings like make_service_request (creates) or get_quote (fetches quote content).

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 invocation context: requires serviceRequestId plus the phone or email from the original request, and explicitly says not to re-call within the same turn when keepPolling is true. It does not name an alternative tool for adjacent needs (e.g., retrieving the quote itself via get_quote), so it falls short of full when/when-not/alternatives coverage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered by structured data. The description adds genuinely non-redundant context: the return is customer pricing only, with vendor cost excluded, and access requires the phone/email on the request — beyond what the annotations 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 primary purpose and contents, followed by requirements and scope caveat. No filler or restatement of the tool name.

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

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

With an output schema handling return structure, annotations covering safety, and 100% schema description coverage, the description only needed to add purpose, prerequisites, and the vendor-cost exclusion — all present. 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 baseline is 3. The description adds meaning the schema does not encode: that the phone or email used on the request is needed alongside the required serviceRequestId, implying an either/or lookup requirement rather than a single required key.

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

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

The description states a specific verb (Get) and resource (customer-facing quote for an existing Detritus request) and enumerates the returned contents: totals, price breakdown by product type, and quote link. This clearly separates it from make_service_request (which creates the request) and the status/availability siblings, which return different artifacts.

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

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

It gives a clear precondition context — the quote is for an *existing* request, and serviceRequestId plus the phone or email used on that request are required. It does not name explicit alternatives or when-not-to-use cases (e.g. vs check_service_request_status), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so 'Read-only.' in the description is pure repetition and earns no credit. The description does add behavioral value by enumerating the categories returned, but it says nothing about what happens for an unserved ZIP or any rate/coverage limits.

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?

Single front-loaded sentence covering purpose and scope, with no filler. The trailing 'Read-only.' sentence is wasted since the annotations already carry that hint, but the overall package is tight.

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 an output schema present, return shape need not be explained, and the one required parameter is documented in the schema. The description covers purpose and scope adequately; only the unserved-ZIP behavior is 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?

Schema description coverage is 100% for the single 'zip' parameter, so the baseline is 3. The description adds only a mild constraint ('US') beyond the schema's pattern definition, which does not meaningfully extend parameter semantics.

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

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

States a specific verb and resource ('Check whether Detritus serves a US ZIP code') plus the full scope of what is listed (dumpster sizes, sanitation products, disposal materials, fencing, storage, water, power). This is unmistakably different from get_quote or make_service_request, so an agent can route 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?

Usage is implied rather than stated: an agent can infer this is the pre-flight availability check before quoting or requesting service, but the description never says when to prefer it over get_quote or make_service_request, nor states prerequisites or exclusions.

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 beyond the annotations by disclosing concrete side effects: it creates a customer record and quote request at Detritus and sends the customer a text and/or email, and it warns 'Not safe to retry' because a repeat call duplicates the request. This usefully reinforces the non-idempotent/destructive hints with real-world consequences, though it says nothing about failure modes or permission 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?

Purpose and the single-request constraint are front-loaded, and the retry warning is placed at the end where it is most salient. The middle sentence enumerating required fields is somewhat redundant against a 100%-covered schema, but overall it is tight and readable.

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

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

For a complex nested mutation tool, the description covers the essentials an agent needs: the confirmation gate, the one-job/one-quote rule, duplicate-call risk, external notification side effects, and the returned id (redundant given the output schema). Only error handling and the upstream get_service_availability ordering 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?

Schema description coverage is 100%, so the schema already documents every nested field, enum, and cross-field rule (e.g. disposalMaterial required when dumpsterSize is set). The description mostly restates the required fields (first name, last name, email, phone, address, delivery date, products, customerConfirmed), adding little beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Submit one quote request to Detritus') and scopes the operation (one request per job = one quote). It is unmistakably the only write/submission tool among read-oriented siblings like get_service_availability and check_service_request_status, so an agent can route to 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 clear conditions: all items for one job go in a single request, and customerConfirmed: true is required only after the customer has reviewed the details. It does not explicitly name alternatives or say when NOT to call it (e.g. call get_service_availability first to obtain product ids), though the schema implies that workflow.

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