Soundcheck Live Event Quotes

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

Beyond the readOnly/openWorld=false/destructive=false annotations, the description discloses that the check is deterministic and local, performs no org write, invents no fixes, and caps input at 256 KiB. It also sketches the return shape (valid, errors with paths, missing_required, schema_version), which annotations alone 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, purpose and timing front-loaded, with no filler — every clause names a rule that is actually enforced. The second sentence is a dense nested run-on that would scan better as a list, which keeps it from a 5.

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, read-only, deterministic validator with an output schema already present, the description covers input constraints, scope of checks, and the nature of the result. 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?

The single parameter's schema description coverage is 100% and already documents the object-or-JSON-string duality the description repeats. The 256 KiB cap is a real constraint but is more behavioral than parameter-shape guidance, 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 (check/validate) and resource (a Soundcheck UEF 2.0 import file) and enumerates the exact rule families enforced. An agent can immediately tell this is a pre-import validator, distinct from format-description siblings like get_import_format.

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?

"check ... before importing it" gives clear timing and intent, and "no AI, no org write, no invented fixes" clarifies what the tool will not do. It does not name any alternative tool or an explicit when-not condition, so it falls 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 cover the read-only, non-destructive, closed-world profile, and the description adds genuinely new behavior: not-found returned for unknown id/domain, and that decision-maker names/emails are gated behind a Team plan for the signed-in member server, so decision_maker_count is only a count. It does not discuss rate limits or caching, but that is minor for a single-entity lookup.

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 dense, front-loaded sentence that leads with the action and the input source, then enumerates returned fields. The field enumeration runs long and partly duplicates the existing output schema, but it reads as informative rather than 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?

Given a single required param, annotations covering safety, and an output schema, the description supplies the missing error behavior (not-found) and the access-control nuance around decision makers. Only minor gaps remain, such as whether the lookup is cached or what domain normalization is expected.

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's description already says "business id from search_businesses, or its website domain such as acmeav.com"; the description restates that same duality plus a maxLength-implied domain example. Baseline 3 applies since the schema carries the 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?

"Get one event business from the directory" states a specific verb and resource plus the cardinality, and the parameter sourcing (id from search_businesses or website domain) makes clear how it differs from the sibling search_businesses listing 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?

Explicitly tells the agent where the input comes from — an id returned by search_businesses or a domain — which implicitly routes the agent to search first when it lacks an id. No explicit when-not-to-use or exclusion is given, so it falls 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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description still adds real behavioral context beyond them: 'no login, no AI, nothing is saved,' which tells the agent there is no auth prerequisite and no side effect of any kind. It stops short of describing the response envelope, though the output schema 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?

Front-loaded with the return payload, then the usage note and routing hint. The first sentence is long and enumerative (clients, venues, acts, projects, gigs, days, run of show, shifts, crew), which is informative but slightly dense; no sentence 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?

For a zero-parameter, read-only reference tool with an output schema, the description supplies everything needed: what the payload contains, that no auth or persistence is involved, and which sibling performs validation. No gap an agent would need to close before calling it.

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 per the rubric the baseline is 4. There is nothing parameter-level for the description to compensate for, and it correctly implies a no-argument call through 'no login, no AI, nothing is saved.'

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 ('Return the format of a Soundcheck import file') and enumerates the delivered payload: UEF 2.0 JSON Schema, linked entities, minimal and festival examples, and a docs URL. It is immediately distinguishable from sibling check_import_file, which it explicitly names as the validator rather than the format source.

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 frames itself as 'A reference for drafting or editing UEF' and routes the alternative case to check_import_file ('checks a draft locally'). The when-to-use condition and the sibling boundary are both stated, nothing 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 already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: the data is seed-only, distinct from CRM data, and absent ids yield a not-found result.

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 with no filler. The scope statement is front-loaded and the caveats (not CRM data, not-found behavior) follow 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?

An output schema exists, so return values need not be described; the description still covers source, identity key, and the negative-result case. Nothing needed to call the tool 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% and the single required 'id' parameter is fully documented there, including the same example (venue_red-rocks-amphitheatre) the description repeats. The description reinforces 'stable id' but adds no syntax or format 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?

States a specific verb ('look up one entry') and a precisely scoped resource ('seeded public industry places catalog by stable id'), which cleanly separates it from the sibling search_places. An agent can tell what it retrieves 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?

Explicitly bounds the data source ('Not org-private CRM data') and states the failure mode ('returns not found when the id is absent from the seed'). It does not, however, name the alternative for finding an id (e.g. search_places), so the routing guidance is implied rather than 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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value beyond them by disclosing the not-found outcome for an unknown slug or id, and by clarifying that only public (not private) data is returned.

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 sentences, front-loaded with the primary action and followed by the error behavior. No filler, though the enumerated return fields slightly overlap with the output 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?

A read-only single-parameter lookup with an output schema present; the description covers what it does, the lookup keys, the returned shape, and the failure mode. Nothing essential for correct invocation 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% and the single identifier parameter is fully documented in the schema, so the description adds little beyond restating 'slug or id'. Baseline 3 applies when the schema already does the work.

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 ('Look up a Soundcheck organization's public profile') and specifies the lookup keys (slug or id) plus the fields returned. No sibling tool covers organizations, so the scope is unambiguous against the rest of the toolset.

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 'public profile by its slug or id', but there is no explicit when-to-use guidance, no statement of prerequisites, and no alternatives named. The not-found line gives a behavioral boundary rather than a selection 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that results are a standard/reference set grouped by section, but says nothing about ordering, pagination, or whether the list is static or event-dependent; with annotations carrying the main load, this is adequate but thin.

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 tightly written sentence that front-loads the verb and resource and closes with the grouping behavior. Every clause earns its place and nothing is padding.

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 tool with an output schema and full annotation coverage, the description supplies what an agent needs to recognize the resource. The one gap is routing: no signal about how this relates to normalize_positions, leaving the sibling choice ambiguous.

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; the baseline of 4 applies. The examples given describe content rather than inputs, which is harmless but adds no 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?

States a specific verb (list) and resource (standard crew positions/roles) with illustrative examples (audio engineer, lighting, stagehand, performer) and the grouping dimension (by section). It does not, however, distinguish itself from the sibling normalize_positions, which deals with the same domain.

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 guidance on when to call this versus alternatives such as normalize_positions or get_uef_schema, nor any prerequisites. Usage is only implied by the 'standard positions' framing, leaving the agent to guess the boundary with its closest sibling.

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, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds genuinely valuable context beyond those annotations: the data is SYNTHETIC and illustrative and 'not a price list any organization charges,' which prevents an agent from treating these as authoritative prices.

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, both earning their place: the first front-loads the catalog contents, and the second delivers the essential synthetic-data caveat. No filler or repetition of structured fields.

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 explained, and the description still provides the enumerable contents and the critical 'synthetic, illustrative' framing. Nothing an agent needs to use the tool 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 parameter semantics are not applicable and the baseline of 4 holds. The description correctly adds no redundant parameter discussion.

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 ('returns') and resource ('the pricing catalog behind quote_event') and enumerates its contents so an agent knows exactly what it retrieves. The mention of 'behind quote_event' links it clearly to the sibling that consumes it, separating it from lookup_market_pricing.

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 strong context for use — 'published so a quote can be checked line by line' — implying it is the reference to consult when validating or explaining a quote. It does not explicitly name an alternative or a when-not condition, so it falls just short of full routing guidance.

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/non-destructive annotations, it discloses substantive behavior: evidence only from published rates and booking aggregates backed by ≥3 distinct organizations, coverage 'none' with null range when evidence is missing, and that prices are never model-invented. These are constraints the agent could not infer from the schema or 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?

The purpose and evidence policy are front-loaded, and the sibling contrast sits at the end where it is most useful. It is dense and somewhat repetitive (the market→region→country walk is stated in both description and schema), but nearly 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?

For a 9-parameter, evidence-driven lookup with an output schema, the description covers the input contract, the fallback resolution behavior, and the guarantee about where numbers come from. Nothing an agent needs to call it correctly or interpret it 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 every parameter, including the 'echoed back, does not filter yet' notes on event_type/guest_count/duration_hours. The description restates those limits and adds the region/country fallback semantics, but adds little syntax-level meaning beyond the schema; 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 (returns evidence-backed market price ranges for named live-event service categories) and enumerates the covered categories. It explicitly distinguishes itself from sibling quote_event, so an agent can route between 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 clear situational context: this is the real-evidence lookup, contrasted against quote_event's synthetic catalog, and it explains the market→region→country lookup walk. There is no explicit when-not guidance beyond that one sibling contrast, so it falls short of a full 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/openWorldHint=false/destructiveHint=false, so safety is covered. The description adds genuinely non-redundant behavior: 'Deterministic alias matching (e.g. SM58 → mic_shure_sm58)' and the scope guard that it does not touch org stock, both of which help predict output.

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, front-loaded with purpose, then return shape, matching behavior, and scope exclusion. Every sentence carries distinct information with no waste.

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, yet the description still briefly names the return shape (mapped[]/unmapped[]) and the deterministic matching rule, plus the key scope boundary. Nothing needed 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% and the sole parameter 'lines' is fully documented in the schema (examples, max items, whitespace handling). The description adds nothing about the input parameter, so 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 ('Map free-text gear lines onto the public Soundcheck inventory catalog') and immediately contrasts itself with search_inventory ('browses the taxonomy'). An agent can distinguish this normalization tool from the browse tool 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 exclusion ('Does not read or write organization inventory stock') and routes to the alternative 'search_inventory browses the taxonomy'. The gap is that the sibling normalize_positions is not addressed, leaving potential ambiguity about which normalizer applies.

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 destructiveHint=false, so safety is covered. The description adds genuinely new behavior beyond them: unknown roles come back as unmapped with fuzzy suggestions, and the tool never writes positions. Return-shape detail is partly deferred to the output schema, which is acceptable.

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 carrying the mapping, examples, sibling contrast, write-exclusion, and fallback behavior with no filler. Every clause 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?

With an output schema present, the description needn't enumerate return fields, and annotations cover the safety profile. What remains — input domain, boundaries, and unmapped-role handling — is fully addressed, so 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% and both parameters are documented there (roles with batch limits, hint with length cap and examples). The description reinforces that input is free-text role strings but says nothing about the hint parameter's effect on normalization, so it adds 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 and resource ('Map free-text crew role strings ... to the Soundcheck global position catalog') and grounds it with concrete labels (FOH, A2, sound guy, LD, stagehand). It explicitly distinguishes itself from the sibling list_positions, so an agent can route 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?

Names the alternative ('list_positions returns the full catalog') and states the negative boundary ('Does not create or write positions'), which cleanly separates mapping from catalog lookup and mutation. It stops short of an explicit trigger such as 'call this when ingesting raw crew sheets', so context is clear but not 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?

Goes well beyond the readOnly/destructive/openWorld annotations: discloses that numbers come from a versioned synthetic catalog plus deterministic engine rather than model invention, that results are not real COGS, and that optional AI grounding sends text to Anthropic via Vercel AI Gateway with zero-data-retention and no storage. That is exactly the extra behavioral context 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?

Front-loads purpose and example, then layers disclaimers and privacy detail. The AI/privacy sentence duplicates the use_ai_grounding schema description nearly verbatim, which is slight redundancy, but the density is justified for a compliance-sensitive estimator.

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, nested-schema tool with an output schema, the description covers the workflow contract (description or quote_id required, requirement overrides, refinement, grounding opt-in) and return-shape expectations; nothing material is left for the agent to guess.

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 earns an upgrade by explaining the interaction between quote_id and requirements (refine vs start over) and clarifying that structured requirements win over the description text, which the schema fields alone only hint at.

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 (returns a cost/budget estimate for a live event) and immediately scopes it as illustrative/ballpark, with a concrete enumeration of event types and an example input. It also distinguishes itself from the sibling request_booking by noting that tool handles a binding vendor price.

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?

Clearly frames itself as an illustrative estimate and points to request_booking for a binding quote, plus explains the quote_id refinement path. It never states an explicit 'use this when...' trigger, but the when-not (not a binding quote) is effectively 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?

Beyond the readOnly/destructive annotations it discloses that nothing is saved or committed, that dates/venues are never invented (absent facts stay null), that text is sent to Anthropic via the Vercel AI Gateway with zero-data-retention routing, and the explicit error behavior when the provider is unconfigured. That is rich, non-redundant behavioral context.

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: the purpose and its output artifacts come first, followed by safety, privacy, error, and hint details. Most sentences earn their place, though 'no login, no organization, nothing is saved or committed' and the parenthetical URL add mild redundancy.

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 no explanation; the description still covers the safety profile, data-privacy path, and unconfigured-provider failure case. Nothing an agent needs to call a zero-required-param parse tool 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 hint, text, raw_input, and format_hint fully. The description restates the hint semantics (event type, locale, or format text|csv|unknown) but adds no extra syntax or format guidance, matching the baseline 3 when the schema does the heavy lifting.

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 and resource ('Read messy live-event material ... into a draft Soundcheck import file (UEF)') plus the exact outputs (missing_fields, open_questions, confidence), so an agent knows precisely what it produces. Accepted input shapes (pasted festival pack, email, rundown, notes) are enumerated, making it self-distinguishing from the sibling import/format utilities.

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 ('Analyze only', 'paste text for now', file upload is a follow-up) and states the failure mode when the AI provider is not configured. It does not, however, name an alternative sibling (e.g. check_import_file / get_import_format) or an explicit when-not-to-use condition for the paste path.

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 the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false). The description adds critical behavior annotations cannot express: nothing is sent until the requester confirms via emailed link, and the request only reaches the organization after the click. That is exactly the kind of non-obvious side effect an agent must know 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-loaded with the action and effect, then requirements, then the confirmation caveat. Every sentence carries information, though the confirmation flow is stated a little redundantly in two clauses.

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 a full input schema, an output schema, and annotations covering safety, the description supplies the one thing structured fields cannot: the deferred, email-confirmed delivery model. Nothing material is missing for correct 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 100%, so all 9 parameters are already documented in the schema; the description merely restates the required set and mentions phone as optional. No new syntax, format, or constraint detail is added, 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 ('Send a booking / staffing request ... to a Soundcheck organization') and the concrete effect ('creates a lead its team follows up on'). This clearly distinguishes it from siblings like request_sponsorship or quote_event.

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 trigger context and lists the required inputs, and the double-opt-in flow tells the agent what to expect after calling. It does not explicitly name an alternative tool or state when-not to use it, 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 only declare the generic profile (not read-only, open-world, non-idempotent, non-destructive). The description adds a genuinely non-obvious behavioral fact: the call does not actually deliver the inquiry — it only emails a confirmation link, and the request reaches the organization only after that person opens the email and clicks Confirm. This double opt-in detail materially changes how an agent should describe the outcome to a user.

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 is front-loaded in the first clause and the confirmation semantics follow. The second sentence is long and somewhat repetitive (the colon clause and the following clause restate the same confirmation step), but every element carries information an agent needs.

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 explained, and annotations carry the safety profile. The description supplies the required-parameter set and the critical confirmation workflow, leaving little an agent needs to know before calling; it only omits disambiguation from sibling write tools like request_booking.

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 defines all 8 parameters, setting the baseline at 3. The description adds only a partial restatement (name, email, optional phone and website) and says nothing about message, estimated_budget, or sponsorship_interest, so it does not meaningfully exceed 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 — 'Send a sponsorship inquiry' — and names the target (a Soundcheck organization) and the effect (creates an inbound sponsor lead it follows up on). It is clear on its own, but it never distinguishes itself from the sibling request_booking, which an agent could plausibly confuse it with.

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 prerequisites ('Requires organization_id, name, and email') which is useful context for invocation, but there is no explicit when-to-use guidance, no exclusions, and no mention of request_booking as the alternative path. Usage is implied rather than directed.

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 safety (readOnly, openWorld, non-destructive), yet the description adds substantial operational context: results are researched from public websites and cached, research.status values ('queued', 'limited', 'paused', 'unavailable') each have a defined meaning, and new listings appear within minutes. It also discloses data provenance ('nothing is invented') and plan gating for decision-maker names/emails, which 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 purpose, then behavior, then the soundcheck linkage — a sensible ordering. The 18-value category list is duplicated verbatim from the schema enum and consumes a large share of the text without adding information, which is the main waste.

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 read-only search with an output schema and rich annotations, everything an agent needs is present: what is searched, what a result contains, why results may be partial, what each research status implies, and how to continue with sibling tools. No material gap remains.

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 documents city/region/country/query/limit/offset/category on its own. The description adds real semantic value by explaining that a category-plus-city combination that has not been researched is queued and returns partial results — behavior the schema only hints at for category alone. It says nothing extra about paging or free-text matching, 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 ('Find event businesses'), enumerates the covered business types, and names the filter dimensions (category, city, free text). It is clearly distinguishable from siblings like search_places or get_business, which operate on places/single records rather than a categorized business directory.

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 for the tool's interesting states (unresearched category+city is queued, 'limited'/'paused' means cached results only) and routes the agent onward: on_soundcheck=true slugs work with get_public_org and request_booking. It stops short of an explicit 'use get_business for full details instead' exclusion, so it is clear context without full when-not guidance.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real scope context beyond that: it returns a catalog version plus stable inventory ids and explicitly is NOT org stock levels, serials, quantities, or pricing, which prevents a common misuse.

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 with the core action and scope front-loaded, then the parameter behavior, then the sibling relationship. Every sentence carries distinct information 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?

With an output schema present, return values need not be spelled out, yet the description still clarifies what is and is not in the payload and routes to the mapping sibling. Nothing an agent needs to invoke 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% for the single query param, so the baseline is 3. The description adds meaning by specifying the filter dimensions (name, alias, id, category), which the schema's example-based text does not enumerate.

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 (Search) and resource (the public Soundcheck live-event gear taxonomy) and enumerates the domains it covers. It clearly distinguishes itself from normalize_inventory by noting that normalize maps free-text lists onto the ids this tool returns.

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?

Explains that the query is optional and that an empty/absent query lists the full catalog, and points to normalize_inventory as the alternative for free-text gear lists. It stops short of an explicit 'use this when X, not when Y' routing statement, so it is clear context rather than full decision guidance.

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, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds genuinely useful non-obvious behavior: results come only from a seeded catalog, unknown names yield empty results with optional name suggestions, and no addresses or geo are ever fabricated. That is real disclosure beyond 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?

Dense but front-loaded: the scoping caveats and return behavior are packed into two efficient sentences with no filler. Slightly cluttered phrasing in the second sentence, but everything 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?

An output schema exists, so return values needn't be fully explained, yet the description still covers the important edge case (empty results plus suggestions). Combined with full schema coverage and clear annotations, 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 coverage is 100%, so query, city, and type are all documented in the schema itself. The description restates the 'name, alias, or id' matching basis but adds no format or syntax detail for city or type beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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 (Search) and resource (public places catalog of venues and hotels), and immediately scopes it by naming what it is not — a complete world database or org-private Soundcheck venues. An agent can distinguish it from get_place 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: this is for well-known seeded venues/hotels, and explicitly excludes org-private venues and full-world lookups. It also sets expectations for misses (unknown names return empty plus suggestions). It does not, however, explicitly route between this and the sibling get_place, so a 4 rather than 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 only declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false); the description adds the destination mechanism (a Linear issue with email fallback), the no-sign-in requirement, and the data-minimization guarantee that only user-approved content is sent. These are concrete behavioral facts an agent cannot derive from 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?

Front-loaded with the core action and audience scope, then mechanism, then the optional-email rule; no filler sentences. It is a long run-on paragraph, which costs a point on structure but not on density.

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 explained, and the description covers everything else that matters: destination, fallback path, auth requirement, privacy scoping, and audience exclusions. Nothing needed 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 description coverage is 100%, so the schema already defines all four parameters including the category enum and email conditionality. The description's 'add the user's email only if they want a reply' restates the email schema, and 'name' is not addressed at all, so baseline 3 is correct.

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 ('send feedback to the people who build this product') and immediately distinguishes the audience from the user's own organization, crew, and clients. It also contrasts itself with the messaging tools, so an agent can tell it apart from siblings 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?

Explicitly says what qualifies (bug reports, feature suggestions, support questions, praise) and what does not ('does not message anyone in the user's organization - the messaging tools do that'). The exclusion plus the named alternative is exactly the when/when-not guidance this dimension rewards.

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