DouxProcess Directory

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

Annotations already cover read-only and closed-world, so the description earns credit for disclosing return fields (phone, website, licence, listing page), ranking order, absence of paid placement, and owner-affiliation disclosure. It omits any pagination behavior even though a 'page' parameter exists.

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, front-loaded with the action and inputs before the return/shape details. No filler, though the opening slightly repeats the tool title.

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

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

With no output schema, the description usefully names what comes back and the integrity/disclosure context. The main gap is pagination, which matters for a tool with a 'page' parameter and no required inputs.

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 60%, so the schema carries most of the load. The description restates query/city/state in prose but adds nothing on the 'page' parameter's semantics or on combining query vs. category filters.

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 ('Search the DouxProcess Directory for businesses') plus the intended lookup axes (need, city, state). Clear that this is a multi-result search versus the sibling get_business, though the distinction is inferred rather than stated.

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 the examples ('roofer, dentist, insurance agency'), but there is no explicit when-to-use, when-not-to-use, or routing to get_business or list_categories. The category-to-list_categories link lives only in the schema, not the description.

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 the safety profile (readOnlyHint=true, openWorldHint=false), so credit goes to the domain context the description adds: it explains the two licence-basis values, that issuer_file is matched against the issuer's own published file at checked_at, and that 'stated' means unmatched. That is real interpretive guidance an agent could not get from the schema, though missing-slug behaviour is unstated.

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, then the licence-basis semantics. The second sentence is dense but every clause earns its place by defining terms the agent must interpret correctly; the parenthetical could be tightened slightly.

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

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

No output schema exists, so the description appropriately enumerates the return contents (details, licences, contact) and pre-explains the licence-basis fields an agent will encounter. Missing only error/not-found behaviour, which for a simple read tool is a minor gap.

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

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

With 100% schema description coverage and a single required parameter whose provenance ('from find_businesses') is already documented, the schema carries the burden. The description adds nothing further about the slug format or validation, 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 concrete verb-resource pair: retrieves one business's details, licences, and contact info. The singular framing implicitly contrasts with the sibling find_businesses, and the slug parameter ('from find_businesses') reinforces the lookup relation, 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?

Usage is implied rather than stated: the schema tells the agent the slug comes from find_businesses, so the call order is inferable. The description adds a genuine downstream instruction ('send the person to source_url' for 'stated' licences), but never says when to prefer this over other siblings or what to do if the slug is unknown.

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 value that annotations cannot: it enumerates the three return fields (NAICS 2022 code, plain name, GBP names), which is important because no output schema exists. It stops short of saying whether the list is exhaustive/static or ordered, but the added context is real.

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 sentence that front-loads the scope ('Every category') and then lists the payload. Zero padding, nothing to trim.

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, read-only lookup with no output schema, the description does the essential job of naming the returned fields. Minor gaps remain — ordering, whether the list is fixed versus dynamic — but 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?

The tool takes zero parameters, so the baseline is 4. Nothing in the description needs to explain arguments, and it does not waste words pretending to.

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 precisely what the tool returns: an enumeration of all categories with their NAICS 2022 code, plain name, and Google Business Profile names. This is clearly a different resource from the siblings (find_businesses, get_business, request_contact), though it never explicitly contrasts itself with them — it relies on the name's verb for the action.

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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives. An agent must infer that this is the lookup to call before resolving business categories; nothing in the text says so.

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 declare readOnlyHint=false and openWorldHint=true, and the description adds genuinely useful context beyond them: exactly which personal data leaves the system (name, contact details, request) and to whom, plus explicit prohibitions on health details, card numbers, ID numbers and passwords. It does not discuss failure behavior, retry/idempotency, or what a successful send returns, which 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?

Front-loaded with the action and its effect, then the gating precondition, then the field-level constraint — a logical order. The embedded consent quote is lengthy but is required verbatim for the agent to display, so it earns its space.

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, non-idempotent, PII-transmitting mutation with no output schema, the description covers the essential safety story: consent gating and forbidden data types. It omits what happens after the send (confirmation, errors, delivery guarantees), which an agent might want before reporting success to a person.

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

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

Schema coverage is only 50% — slug, email and phone carry no descriptions — yet the description says nothing about slug format or when email vs. phone should be supplied. It only reinforces meaning for consent ('only if they agreed') and constrains details content (no health/card/ID/password data), so it partially but not fully compensates for the coverage gap.

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 ('sends the person's request to the ONE business they chose') and the resulting effect ('so it can reply to them'). This clearly distinguishes it from the sibling lookup tools (find_businesses, get_business, list_categories), which do not transmit anything.

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 precondition: 'Call only after the person has read and agreed to this' followed by the verbatim consent sentence, plus a rule for setting consent=true only when agreement is given. Nothing about when to call 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.