KOB Live Restaurant Ops Audit

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so 'Read-only' is largely redundant. The real added value is the disclosure of return contents and the strict output-fidelity constraint ('Never invent hours, ratings, or revenue') plus the 'when available' caveat on Yelp, which tells the agent to expect missing-source handling rather than a hard failure.

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 with the core action front-loaded, followed by outputs, then the constraint. Nothing is padding except 'Read-only', which duplicates the readOnlyHint annotation. Efficient and skimmable.

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 enumerates the return payload, and annotations cover safety. But a zero-required-parameter, openWorld tool never explains which identifier combinations actually drive a lookup (placeId vs location vs googleMapsUrl vs websiteUrl), leaving the agent to guess at a valid invocation.

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

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

Schema description coverage is 57%, so several parameters (name, placeId, googleMapsUrl) carry no documentation anywhere. The description adds no parameter meaning at all: it does not explain how name/placeId/location/websiteUrl relate, which are sufficient to run an audit, or what 'when available' implies for websiteUrl overrides. This is a clear compensation 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?

The description states a specific verb (Compare) and enumerates the resources it reconciles: the public Google listing, the restaurant website, and Yelp. It also names the concrete artifacts produced (score, discrepancies, impact notes, data gaps), which distinguishes it from the single-source siblings get_google_listing and get_yelp_listing. It stops short of explicitly routing agents away from those siblings, so it is not a 5.

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 composite framing implies when the tool is appropriate (cross-source reconciliation rather than a single lookup), and the schema-level 'example' parameter implies a demo path. However, there is no explicit when-to-use, no when-not-to-use, and the sibling tools that fetch individual sources are never named as the alternative for narrower 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?

Goes well beyond the annotations by disclosing the actual sink chain: POST JSON to LEAD_WEBHOOK_URL, fall back to emailing only the KOB inbox via Resend, and fall back again to server-side logging with the lead still returned. It also rules out side effects (no restaurant email, no Google mutation), which the openWorldHint=true annotation cannot express on its own.

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 the action and its precondition, then packs the sink/fallback behavior into tight conditional clauses. Dense but every sentence carries load; only the back-half fallback detail could arguably 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 9-parameter, non-idempotent, open-world write with no output schema, the description covers the important unknowns: what is transmitted, where it goes, what happens on each configuration fallback, and what is never done. It leaves return-value shape slightly vague ('the result still contains the lead') but that 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?

Schema description coverage is only 33% across 9 params, so the description must compensate and it only partly does: it explains that consent must be true and that auditSummary is a short, verified-findings-only summary. Fields like town, email, notes, placeId, website and restaurantName get no elaboration here, though the self-explanatory names carry 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?

States a specific verb+resource ('Record a trial lead') plus the trigger condition, which is enough to distinguish it from every sibling (none of which touch leads). An agent can tell immediately this is the outbound lead-capture sink, not an audit or lookup tool.

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 ('after the user typed their details and asked to be contacted') and two exclusions ('Never email the restaurant. Does not change Google.'). It stops short of naming an alternative sibling to use instead, but for a terminal capture action there is no competing tool to route to.

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 meaningful behavior beyond them: drafts are never posted, reviews with existing owner replies are skipped, and fabrication is explicitly forbidden. It does not mention auth requirements, rate limits, or what the returned drafts look like.

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?

Five short sentences, each carrying a distinct constraint, with purpose and the never-posted guarantee front-loaded. Nothing is repeated from the schema or the 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 no-required-param, no-output-schema tool the critical behavior (drafts not posted, no fabrication, skip already-replied) is covered. The remaining gap is which location identifier to supply when reviews come from Google, which neither the description nor the schema resolves.

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%. The description clarifies the dual source of the reviews parameter (user-pasted vs Google-returned), matching that param's schema text, but says nothing about the undocumented placeId, googleMapsUrl, or restaurantName fields, leaving the agent guessing how to target a restaurant.

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 (draft) and resource (owner replies to reviews), plus the two input sources: reviews the user pasted or that Google returned. No sibling tool touches reviews, so the agent can identify this tool immediately without conflict.

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 exclusions — skip reviews that already have an owner reply and do not invent reviews — which tell the agent when not to act on a given review. It stops short of naming an alternative tool or stating the top-level triggering condition a user must satisfy.

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, openWorldHint and destructiveHint=false, so the trailing 'Read-only' is largely redundant. The one genuine addition is 'when the Places API returns them', which warns that fields may be conditionally absent — useful, but thin for a live external API call.

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 tight, front-loaded sentences with the verb and resource first and the returned fields enumerated compactly. The only wasted phrase is 'Read-only', which duplicates the annotation.

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 enumerates the returned fields, which is appropriate. However, it omits the crucial input story (placeId vs googleMapsUrl, whether either is required) and gives no signal on how to disambiguate from the Yelp sibling.

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%, with placeId and googleMapsUrl completely undocumented in both schema and description. The description never explains that these are alternative place identifiers, whether one is required, or how they interact — a real gap for a lookup tool whose core parameter semantics are unstated.

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 ('Fetch') and resource ('public Google place details') and enumerates the returned fields (hours, phone, website, rating, review count, reviews), so an agent knows exactly what it produces. It does not explicitly contrast with the sibling get_yelp_listing, leaving source differentiation to the tool name alone.

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?

No when-to-use guidance and no alternatives are named, despite get_yelp_listing and find_restaurant being obvious siblings. The agent must infer that this is the Google-source lookup tool from the name only; nothing states when to prefer it or how it differs from the Yelp variant.

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