GigXchange

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

Adds substantial context beyond the annotations: rate limits (one live application per gig, 5 per day), the prerequisite 'Allow my assistant to act' switch, and the key semantic that the fee is derived from the gig's listed budget with no fee input. This explains the destructiveHint/idempotentHint pairing in operational terms the agent needs.

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 compact sentences, front-loaded with the action and its source, followed by fee semantics, limits, and the prerequisite. No filler and no repetition of the 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?

For an action tool with no output schema, the description covers origin of the id, side-effect semantics, quota limits, and the authorization switch — everything needed to invoke correctly. Nothing material is left for the agent to infer.

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 gig_id and note are already documented, warranting the baseline 3. The description adds real meaning on top by clarifying that no fee parameter exists and that the fee is sourced from the gig budget, heading off an agent attempt to pass a price.

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 ('apply') and resource ('open gig'), and pins the object's origin to search_open_gigs with a scope qualifier ('GigXchange member-posted gigs only'). An agent can distinguish this from make_offer and respond_to_booking without reading 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?

Names the upstream tool that produces valid gig_ids (search_open_gigs) and states the prerequisite switch, giving clear context for when the call will succeed. It stops short of explicitly naming the adjacent alternatives (make_offer, respond_to_booking) and when-not to use them.

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 a closed world, so the safety profile is covered. The description adds genuinely non-structured context by defining the semantics of the result: "free-by-default" — available simply means nothing is marked against that date. It does not mention behavior for unknown/ambiguous member ids, but the core interpretive rule is supplied.

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 with no filler: the single-member/date scope is front-loaded, the free-by-default rule follows, and the routing hint comes last. 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?

For a two-parameter read-only lookup with full schema coverage and no output schema, the description is nearly complete; the return shape need not be explained. Only minor edge cases (nonexistent member, ambiguous slug) are left unspecified, which is a small residual 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 100%, so both parameters are already documented and the baseline is 3. The description adds only marginal meaning — that the member may be an artist or a venue and that the id comes from a search/get_profile result — while the schema carries the slug/date format detail.

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), specific resource (ONE named member), and specific scope (free on a specific date), then immediately differentiates itself from the nearest sibling: finding WHO is free belongs to search_available_performers. An agent can pick between them 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?

Explicitly gives the triggering question ("is X free on the 14th?") and names the alternative tool plus the condition that selects it ("finding WHO is free is search_available_performers"). Both the when-to-use and the when-not-to-use are 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?

Annotations only say this is a non-read-only, non-idempotent, destructive mutation; the description goes well beyond that by disclosing the chat side effect (the old offer card is retired), the per-day rate limit, the optimistic-concurrency guard on expected_current_fee, and the required member consent toggle. This is exactly the behavioral context annotations cannot carry.

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 chat side effect, then the validation rules and prerequisites. Dense and largely waste-free, though the run-on second clause packs three distinct constraints into one sentence, slightly straining readability.

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 mutation tool with no output schema, the description covers side effects, rate limits, concurrency requirements, and authorization. It stops short of describing the failure/response surface (what the caller sees on rejection), which would fully close the loop, but the essential invocation context is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: expected_current_fee must MATCH the booking (a concurrency/safety guard, not just 'the current fee'), and new_fee is constrained to 50-200% of it. That is meaning beyond the schema's field-level text.

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 precise verb (propose a different fee / counter) on a specific resource (a pending booking offer), and the parenthetical spells out the side effect — an amended offer card posted in chat, retiring the old one. This is clearly distinguishable from make_offer and respond_to_booking 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?

Gives clear context ('on a pending booking offer') and concrete preconditions: a matching expected_current_fee, a 50-200% fee band, one counter per booking per day, and the member's 'Allow my assistant to act' switch. It never explicitly names respond_to_booking or make_offer as the alternatives to choose between, so it stops short of full when/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, idempotentHint, non-destructive, and a closed-world scope, so safety is fully covered. The description adds that the EPK is public and that the response carries summary, genres, rating, and media counts, which is modest but real added 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?

One compact sentence with the resource front-loaded, the lookup key next, and the return fields in parentheses. No sentence is wasted and nothing important is buried.

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 and labels the data public, which is enough for a one-parameter read tool. Behavior on a missing or invalid slug, and any rate-limit or auth nuance, is left unstated.

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 slug parameter, so the schema already carries the semantics. The description's 'by URL slug' restates the schema rather than adding format or resolution rules (e.g. how a slug is derived or what happens on a miss), which is the baseline 3 case.

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 resource (an artist's public electronic press kit) and the lookup key (URL slug), plus the returned payload shape. It is distinguishable from generic siblings like get_profile or get_venue, though it never explicitly contrasts itself with them.

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 prerequisites, and no mention of an alternative or complementary tool. The word 'Public' hints that no authentication is needed for this data, but that is inference rather than stated 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, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds that this is public detail and lists returned content areas, but does not mention auth requirements, error behavior, or rate 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?

A single, front-loaded sentence with no wasted words. It efficiently communicates resource, scope, required input, and return content.

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

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

For a simple public retrieval tool with complete annotations and full schema coverage, the description is nearly sufficient: it names the slug input and the returned content areas. Minor gaps remain around error/not-found behavior and response structure, but no output schema exists to rely on.

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

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

Schema coverage is 100% for the single slug parameter, so the schema already documents the required input. The description reinforces 'by URL slug' but adds no syntax, format, or validation detail 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?

The description states a specific resource and scope: public event detail on GigXchange retrieved by URL slug, including the kinds of data returned. It distinguishes an event from gigs/venues implicitly but does not explicitly contrast with sibling tools like get_gig or get_venue.

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 'by URL slug' and 'public detail,' suggesting it is for retrieving an event when the slug is known. However, the description gives no explicit when-to-use guidance, prerequisites, or alternatives to sibling lookup tools.

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 the safety profile is covered. The description adds value beyond them by disclosing the payload contents (line-up, address, times, tickets), which matters since there is no output schema; it stops short of 5 for omitting any auth or not-found behavior.

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 with the primary purpose front-loaded and the parameter-source hint trailing. No filler words.

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

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

For a simple two-parameter read tool whose annotations cover safety and whose fields are enumerated in the description (compensating for the absent output schema), this is nearly complete; only edge-case behavior such as a missing gig is unaddressed.

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 both parameters are already documented with their sources. The description's 'use the city_slug + slug from a search_gigs result' largely restates the schema, so it lands at the baseline 3 for high-coverage schemas.

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 (get/fetch) and resource (a single directory gig) and immediately lists what it returns — line-up, address, times, tickets. The word 'single' combined with the explicit pointer to 'a search_gigs result' distinguishes it from the plural search_gigs sibling.

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?

'Use the city_slug + slug from a search_gigs result' gives clear workflow context and names the sibling that produces the inputs. It lacks an explicit when-not-to-use clause (e.g. versus get_event/get_venue), so it stops short of 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description's only added disclosure is that the return is the 'full text' of a single article — useful since no output schema exists, but thin beyond that.

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

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

A single front-loaded sentence with no filler; resource and scoping constraint appear before the sourcing detail.

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 trivial one-parameter read tool whose annotations cover the safety profile and whose description names the return content and slug source, there is little missing. Only the absence of error/not-found behavior keeps it from a top score.

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 one parameter at 100% schema coverage, the schema already documents the slug. The description only reinforces that the slug originates from search_help, adding no format or syntax detail beyond the schema's own description.

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 (read the full text of one help article) and scopes it to 'one official article,' which cleanly separates it from search_help and list_help_topics. It names the sibling source of the slug, though it stops short of contrasting against the other get_* retrieval tools.

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 phrase 'by slug from a search_help result' establishes the required workflow precondition — you must have searched first to obtain the slug. No explicit when-not guidance or comparison to alternative retrieval tools, but the context is clear.

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, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. With no output schema, the description adds real value by enumerating the payload: headline description, key figures, context, FAQ, PDF and open-dataset links. It does not describe behavior for a missing/invalid slug.

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 front-loaded sentence that identifies the resource, the key, and the return contents with zero 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?

Because no output schema exists, the description compensates by listing what the issue contains, which is enough for an agent to judge relevance. Minor gaps remain around invalid-slug behavior, but for a 1-parameter read tool this is close to complete.

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 slug parameter already carries the format example, so the description's slug example is largely redundant. The only added meaning is pointing to get_index_summary as the source of valid slug values, which is closer to usage guidance than 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 (get) and resource (one published GX Index monthly issue) plus the retrieval key (slug). It explicitly distinguishes itself from the sibling get_index_summary, which lists issues rather than returning one.

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 get_index_summary as the way to discover valid slugs, which implicitly tells the agent when to use that tool instead of this one. There is no explicit exclusion or failure-handling guidance (e.g. what happens with an unknown slug), 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 the safety profile is covered. The description adds meaningful context by disclosing the shape of the payload (issue list, dataset links, league table), which the annotations do not. It stops short of noting pagination or freshness of the monthly issues, so it is not a full 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 resource identity, then the payload contents, then routing to alternatives in a compact second sentence. The middle enumeration is dense but each clause describes a distinct returned section, so little is wasted; slightly long for a zero-parameter tool.

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?

Zero params, no output schema, but the description enumerates the returned sections in enough detail (issue slug/title/url, HuggingFace/Kaggle/Zenodo DOI datasets, city league) that an agent knows what it will receive. Complete for this tool's complexity.

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?

Zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond confirming this is a parameterless overview call. The description's enumeration of returned sections is helpful context, not param 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 resource (GigXchange Index / GX Index) and enumerates exactly what the overview returns: headline counts, cities, published monthly issues with slug/title/url, latest issue datasets, and the city average-fee league. An agent can distinguish it from get_rates and get_index_issue 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?

Explicitly says 'Use for any GX Index question' and routes the two adjacent cases to alternatives: fees to get_rates, single issues to get_index_issue. When-to-use and when-not-to-use are both stated.

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

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

Annotations already declare read-only, idempotent, closed-world, non-destructive behavior, so the safety profile is covered. The description adds the one thing annotations cannot: what the call actually returns ('full editorial text' plus a member profile link), which is valuable given there is no output schema.

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 sentence, zero filler, and the payload ('full editorial text of one Member Spotlight issue') is front-loaded before the secondary detail about the profile link.

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-record read tool with rich annotations but no output schema, the description supplies exactly what is otherwise missing: the shape of the returned content (editorial text plus profile link). Nothing an agent needs to call it correctly is absent.

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 slug parameter is fully documented in the schema, including its source. The description's phrase 'by slug' confirms the key but adds no format or validation 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 precise action and resource: retrieving the full editorial text of one Member Spotlight issue, keyed by slug. The singular, slug-addressed framing cleanly separates it from the sibling list_member_spotlights, so an agent can pick it without opening the schema.

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

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

Usage is only implied: 'by slug' tells the agent it needs a slug, and the schema points to list_member_spotlights as the source, but the description itself gives no when-to-use statement or alternative. Adequate minimum, no explicit routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds useful content-scope information by enumerating what the response includes, which is the main behavioral fact an agent needs here.

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 short sentences, zero filler, with the resource scope front-loaded before the slug-provenance instruction. 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?

No output schema exists, but the description compensates by naming the key returned fields, and the single required parameter is fully covered. 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% and the single slug parameter is already documented identically in the schema. The description's only param-adjacent sentence repeats the schema's provenance note, adding no format or syntax detail, 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+resource (full detail for a single open mic night) and enumerates the fields returned: schedule, signup, slot length, backline, address. It also implicitly contrasts with search_open_mics, so an agent can distinguish detail-fetch from list-search.

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?

"Use the slug from a search_open_mics result" tells the agent the prerequisite and the natural workflow (search first, then fetch detail). It doesn't state exclusions, but for a single-purpose detail tool none are really needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: the counts are 'live', and the 'upcoming gigs' figure is scoped to the directory/concerts rather than application listings. It does not describe count freshness guarantees or caching, but the annotations lower the bar.

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: the metric categories come first and the disambiguation parenthetical comes last. Every clause carries information, with no filler or restatement of the 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 parameters and no output schema, the enumerated categories (members by type, venues, open mics, cities, upcoming gigs) effectively stand in for the missing return shape, which is a real strength. It stops short of guaranteeing the exact response keys or whether counts are paginated/snapshotted, so it is strong but not exhaustive for a schema-less read.

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 under the rubric. There is nothing for the description to disambiguate on the input side, and it correctly avoids inventing filter semantics that the empty schema would not support.

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 (live counts) and resource (platform stats across GigXchange), and enumerates exactly what is counted: members by type, venues, open mics, cities, upcoming directory gigs. It further distinguishes itself from siblings by explicitly noting that open-application gigs live in search_open_gigs rather than here.

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 parenthetical clarifies the semantic scope of the gig counts and routes some queries to search_open_gigs, which is useful disambiguation. However, it never states the general condition for reaching for this tool (e.g. 'use when you need an overview/summary of platform activity'), so usage is only implied rather than instructed.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world. The description adds that the profile is public and enumerates visible fields, which is useful context, but does not discuss auth requirements, missing-slug behavior, or rate 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?

A single, front-loaded sentence with no wasted words. The lookup key and returned fields are immediately visible.

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

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

For a one-parameter read-only tool with rich annotations, the description is nearly sufficient: it names the resource, key, and returned data. It omits only edge behavior such as not-found response, which is minor here.

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 slug parameter is already documented with an example. The description reinforces that lookup is by URL slug but adds no syntax or semantic detail 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?

The description states a specific verb+resource (get public profile for a GigXchange member) keyed by URL slug, and lists the returned fields. It does not explicitly differentiate from siblings like my_profile or get_venue.

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: fetch a public member profile by slug. There is no explicit guidance on when to use this versus my_profile, get_venue, or get_epk, nor any exclusions or prerequisites.

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 true and destructiveHint false, so the safety profile is fully covered by structured data. The description does add return-value semantics (percentiles, sample size, honest regional/UK-wide/modelled labels) and the caveat that these are typical published take-home fees, not a quote, which is genuinely useful context 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?

Front-loaded with what the tool returns before the usage examples, and nearly every clause carries information (source, statistic, caveats, exclusions). It is a single dense paragraph, which reads as slightly run-on, but there is little 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?

No output schema exists, and the description compensates by explaining the shape and meaning of results (median, range, sample size, data-quality labels). With annotations covering safety and the schema covering parameters, an agent has everything needed to call this 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 schema already documents all three parameters including defaults, fallback behaviour and enum meanings. The description mainly reinforces existing constraints (pass a city not a region, omit for UK-wide, several cities to compare) rather than adding new syntax, so it sits at the high-coverage baseline.

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 with the exact statistic returned (median and 25th-90th percentile fees by city, gig type and act size) and names the data source (GigXchange Index). It is clearly distinguishable from siblings like get_index_summary or list_cities, which supply the city/issue inventory rather than fee figures.

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 concrete triggering questions ("what should my band charge", "what does a wedding band cost in Leeds") and an explicit comparison workflow ("pass several cities to compare"). It also states exclusions directly: regions are not accepted, pass a city; there is no genre dimension.

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 the safety profile is fully covered. The description adds no behavioral context beyond that (no pagination, freshness, or auth notes), making it adequate but not rich.

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 sentence that front-loads the scope and field list, followed by a short routing hint. Every clause earns its place with no 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?

With no output schema, the description helpfully enumerates what a 'full' venue record contains and how to obtain the required slug. It is close to complete, though it omits edge cases such as what happens for an unknown or stale slug.

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 'slug' parameter already carries the description 'Venue slug from a search_venues result.' The description repeats that guidance almost verbatim, adding no format or syntax detail beyond the schema, so the baseline of 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 ('Full detail for a single grassroots venue') and enumerates the exact fields returned (capacity, PA, backline, genres booked, curfew, address), which cleanly distinguishes it from the sibling search_venues list 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 to 'Use the slug from a search_venues result,' which establishes that this tool follows a search as the retrieval step for one record. It gives clear context but does not state any when-not or exclusion conditions.

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 the safety profile is fully covered without description help. The description contributes the return content ('with a member count each'), but says nothing about ordering, pagination, or completeness of the list. Adequate, not rich.

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 short sentences, zero filler, with the resource and its contents stated before the usage hint. 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 no parameters and no output schema, the description usefully pins down what a call returns (city name plus member count). It is complete for the task; only list-shape details like ordering or size limits are absent, which is minor here.

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 clarify; baseline for a no-parameter tool 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 resource (UK cities where GigXchange has members) plus the payload each entry carries (member count). No sibling tool lists cities, so the resource alone disambiguates it from list_help_topics, list_member_spotlights, and the search_* family.

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 triggering question: 'do you cover <city>?'. That is clear situational guidance, but it names no exclusions or alternatives (e.g. that venue-level coverage should go to search_venues instead).

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: this is an exhaustive closed-world enumeration, and absence from the list means absence from the help centre. Return format detail is still absent.

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 short sentences, no redundancy, and the core capability is front-loaded before the usage guidance. 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?

With no output schema, the description compensates by sketching the return contents ('every category and the questions it answers'). For a zero-required-parameter, read-only listing tool this is fully sufficient to call 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?

There is one optional 'category' parameter with 100% schema description coverage including an example value. The description never mentions the filter and only describes the unfiltered 'every category' view, so it adds nothing beyond the schema — 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?

The description states a concrete resource and scope: 'the full map of GigXchange's official help centre — every category and the questions it answers.' The exhaustive framing implicitly separates it from search_help (query-driven) and get_help_article (single article), but no sibling is named outright.

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 trigger ('what can you help me with?') and a boundary condition ('Topics not listed here are not covered by the help centre'). It stops short of routing the agent to search_help or get_help_article for narrower questions, so it is context-rich but not alternative-aware.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds genuinely useful non-annotation context — that only 'published' features appear and that results are ordered newest first — but says nothing about pagination, result count, or what a list entry contains.

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

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

One tight sentence with a clarifying em-dash gloss, and the resource identity plus ordering constraint are front-loaded. No filler or redundant restatement of the 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 parameters, no output schema and annotations covering safety, the description supplies the essentials: what the index contains, that it is published-only, and the sort order. Minor gap is the absence of any hint about list size or pagination, which for a zero-param index is acceptable.

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 and the baseline of 4 applies. No parameter claims are made that could be wrong.

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 resource ('Member Spotlight features') and adds a clarifying gloss — 'long-form profiles of real GigXchange members' — so an agent knows what the content actually is. It is clearly distinct from the singular get_member_spotlight sibling by being an index/listing, though it never names that sibling explicitly.

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

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

The word 'Index' plus 'Newest first' implies a browse-the-catalog use case, which contrasts implicitly with get_member_spotlight for fetching one issue. However, there is no explicit statement of when to use this versus fetching a single spotlight, so the routing 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.

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

Annotations only flag destructive/readOnly/idempotent, but the description adds real behavioral context: side effects on the recipient, three distinct rate limits (max 5/day, one per recipient/day, no duplicate live offer for a date), and the prerequisite "Allow my assistant to act" switch. That is substantial disclosure beyond the structured fields, with no contradiction of 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?

Front-loads the purpose before the em dash, then packs constraints into a tight clause series with no filler. It reads as one long run-on sentence, which slightly hurts scannability, but nearly every clause carries an operational constraint.

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 mutating tool with no output schema, the description covers side effects on the recipient, eligibility, rate limits, and prerequisites. It could say what the caller receives back (e.g. whether an offer id or pending booking reference is returned), but everything needed to call it correctly is present.

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

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

Schema description coverage is 100%, with units, formats, and ranges already documented for all seven parameters (GBP 1-100000, YYYY-MM-DD, HH:MM, slug/id). The description adds no parameter-level detail, so the baseline of 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 offer") plus the target actor ("another GigXchange member"), and immediately clarifies the recipient-side effect (pending booking, notification, offer card). This lets an agent distinguish it from respond_to_booking, counter_booking, and apply_to_gig 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?

Gives explicit eligibility rules: supported role pairs (venue/promoter/organiser to artist, artist to venue/promoter, promoter to venue) and a clear when-not (offers involving an agent are app-only). It does not name the sibling alternatives (e.g. counter_booking for negotiating back), so routing among similarly named booking tools is left partly 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the mutation profile is covered. The description adds a genuinely non-obvious prerequisite – the member's 'Allow my assistant to act' switch – which is exactly the kind of authorization context annotations cannot express.

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 short sentences with zero waste: the action and its scope come first, and the permission prerequisite follows immediately. Nothing is padded or repeated.

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, no-output-schema action, the description covers what it does, the scope, and the authorization gate. It could mention that the change is not reversible (consistent with destructiveHint=true), but nothing essential 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline is 4. It does usefully clarify the scope of the operation ('all of the member's notifications') rather than implying any selectable subset.

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

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

The description names a specific verb ('mark ... as read') and resource ('the member's GigXchange notifications') plus the scope ('all'). It is unambiguous and clearly distinct from siblings like my_unread_messages, though it does not explicitly name or contrast any alternative 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?

Usage is implied: you call it when you want to clear the member's notification list. It does not say when to prefer this over alternatives (e.g. reading individual messages) or whether the action can be undone, so guidance is only at the minimum-viable level.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description adds genuinely useful domain context beyond them: the free-by-default bookability model and the meaning that returned dates are the exceptions (unavailable / soft_hold / confirmed_booking). This semantic framing is not recoverable 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?

Three tight sentences with the core scope front-loaded, followed by the model explanation and the window limits. No filler; every sentence carries distinct 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?

With no output schema, the description carries the return-value burden, and it does so by naming the categories of marked dates the tool returns. Slightly short of a 5 because it doesn't describe the response shape (fields per marked date), but the semantics are clear enough to call 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% and the schema already documents both dates, their YYYY-MM-DD format, the 90-day default and 365 cap. The description merely restates the same defaults and caps, adding no new syntax or format detail 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 precise verb+resource combination ('The member's OWN availability for a date window'). The capitalized 'OWN' implicitly contrasts with sibling tools like check_member_availability, letting an agent distinguish them without opening schemas.

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 'OWN' framing and the free-by-default explanation, but no alternative is named explicitly (e.g. 'use check_member_availability for another member'). The agent must infer when this tool is the right pick versus the other availability siblings.

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 this as a safe, idempotent, read-only, non-open-world operation. The description adds useful behavioral context beyond annotations by specifying the 30-day lookback window, the fields returned, and the 25-row cap.

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

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

The description is a single compact sentence that front-loads the scope and then lists returned fields and the row cap. It is efficient, though the 'Max 25' clause slightly duplicates the schema's limit description.

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

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

For a simple read-only list tool with rich annotations, a fully documented single parameter, and no output schema, the description provides enough context to invoke it correctly. Minor details like ordering are omitted but are not essential for correct selection.

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 sole 'limit' parameter is fully documented in the schema. The description repeats the max of 25 but does not add new parameter semantics such as default behavior or sort interaction, so the baseline of 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?

The description clearly identifies the resource as the member's own bookings and specifies the date scope, returned fields, and row cap. It is distinguishable from broader sibling tools like search_gigs or get_gig, though it does not explicitly name alternatives.

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 'member's own bookings' and the 30-day window, but the description does not explicitly state when to use this instead of siblings such as get_gig, respond_to_booking, or my_invoices. No exclusions or alternative-routing guidance are provided.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value on top: it discloses that each row carries a direction discriminator and that payment-processor identifiers are deliberately withheld, which is behavior an agent cannot learn from the schema.

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 dense sentence front-loads the payload (status and amounts), then qualifies scope (both directions) and the direction values. There is no filler or restatement of the 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?

There is no output schema, so the description carries the burden of describing returns, and it does so partially — status, amounts, and the direction field are named, plus a privacy boundary. It omits ordering, pagination/volume, and amount formatting (currency), which are minor but real gaps for a no-output-schema tool.

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, which is the baseline-4 case. There are no argument names for the description to explain, and it correctly spends no words on nonexistent inputs.

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

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

The description names a specific resource (the member's invoices) and scope (both sent and received), making it easy to separate from siblings like my_bookings or my_profile. It is clear and specific, but never explicitly contrasts with submit_my_invoice, the write-side sibling an agent might 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?

Usage is implied by the name and the zero-parameter signature — there is only one sensible thing to do with this tool — but the description provides no explicit when-to-use or when-not, and does not name submit_my_invoice as the alternative for creating rather than viewing invoices.

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 the safety profile is covered. The description adds a real precondition beyond the annotations ('Requires a connected account') and enumerates the returned fields, which matters since there is no output schema. It stops short of saying what happens when the account is not connected.

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 short sentences, zero filler: the resource and scope come first, the returned fields second, the precondition last. 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?

For a zero-parameter read tool with full annotation coverage, the description supplies what the structured data cannot: the identity scope, the field list (no output schema exists), and the connected-account precondition. The only real gap is the absence of an explicit pointer to get_profile for other members.

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 schema has nothing to document and there are no parameter semantics for the description to clarify. Baseline 4 applies; no parameter-level value is added or lost.

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

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

The description names a specific resource with scope ('the signed-in member's own profile') and enumerates the fields it returns, which an agent can act on immediately. It distinguishes itself implicitly from the sibling get_profile via 'own', but never names that sibling explicitly, so the routing signal is weaker than it could be.

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 precondition 'Requires a connected account' is stated, which is genuinely useful context, but there is no explicit when-to-use guidance or a named alternative (e.g. use get_profile for another member). Usage is only implied by the word 'own'.

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-open-world and non-destructive, so the safety profile is covered. The description adds genuine value beyond that by disclosing the return shape — a COUNT only, with message contents never exposed — which is important for an agent with no output schema.

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 core purpose and immediately followed by the one caveat that matters. Zero filler.

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

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

For a no-parameter read tool with no output schema, the description covers both what it does and what comes back (a count, no contents). An agent has everything it needs to invoke and interpret this 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?

The tool takes zero parameters, so the baseline is 4. Nothing in the description is needed to clarify inputs, and nothing misleading is added.

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

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

States a specific verb and resource: counting the member's unread messages. This is clearly distinguishable from siblings like mark_my_notifications_read (which mutates read state) and send_chat_message (which writes).

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 indication of when to reach for this tool versus alternatives such as mark_my_notifications_read, nor any prerequisites or exclusions. The title implies an obvious use case, but the description itself gives no 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 annotations (destructive, non-readOnly, idempotent) the description discloses a fee-match guard that refuses stale calls, a rate limit of 3 declines per day, a side effect (accepting can start the payment flow), a relayed message to the other party, and an enabling precondition (the 'Allow my assistant to act' switch). These are exactly the hidden traits an agent needs.

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 scope, then each following clause adds a distinct precondition, guard, or consequence. No filler sentences; every clause carries operational 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?

With no output schema and a simple flat param set, the description supplies everything else needed to invoke this mutation correctly: who can call it, which offers qualify, the fee-match guard, the decline rate limit, the decline note requirement, and the payment side effect.

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 75%, with the action enum and booking_id already documented. The description still adds real meaning: it explains expected_fee is a validation guard (must equal the current fee or the call is refused) and that note is mandatory when declining and is relayed to the counterparty.

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 pair (accept/decline) and an equally specific resource (a booking offer), then immediately scopes it: only offers the member RECEIVED, never one they sent. That scope clause cleanly separates it from siblings like make_offer and counter_booking without needing to read 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?

Gives explicit when-to-use (respond to a received offer) and a strong when-not ('never one they sent'), plus declining constraints. It stops short of naming the alternative tools (e.g. counter_booking for a counter-offer), so it is clear context with an exclusion rather than a full routing map.

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/idempotent annotations by disclosing the FREE-BY-DEFAULT booking model, including the critical interpretation rule that a large result means 'nobody blocked that day' rather than 'everyone is free'. It also states each result carries the `id` downstream tools need, and that output is paginated.

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 purpose, then the caveat, then the return contract, then filters and pagination. Dense but nearly every clause carries information; the act_type enumeration duplicates the schema slightly but is defensible as an error-prevention measure.

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 takes on the return-value burden and does so: it explains what each result contains (the member `id`) and how to read the result set size. A 5-parameter search tool with one required param is fully specified 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 coverage is 60%, with limit/offset carrying no descriptions. The description compensates by flagging pagination and the optional city filter, and it restates the act_type allowed values, which reduces the chance of an invalid enum value being sent. It still adds no syntax or format detail for the pagination parameters.

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+scope: artists/bands open to a booking on a specific date. It is instantly distinguishable from siblings like search_available_venues and check_member_availability, and the title reinforces the date-specific framing.

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

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

Gives clear usage context by naming the downstream tools that consume the returned `id` (make_offer, check_member_availability), which implicitly tells the agent this is a discovery step, not a confirmation. It also warns the result is 'not a confirmed yes', steering toward check_member_availability. However, it never explicitly states when to prefer this over a different search or what the follow-up sequence should be.

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, so the safety bar is met elsewhere. The description adds meaningful behavior beyond them: the free-by-default availability model (open unless the venue marked that date), pagination, and the important limitation that hiring is not supported and no hire rates exist.

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: purpose, availability semantics, the hire-vs-request warning, filtering and pagination all in a few tight sentences. Every clause earns its place with no filler.

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

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

With no output schema and one required parameter, the description covers purpose, availability semantics, filtering, and pagination, which is enough to call it correctly. It could note the result shape or default page size, but nothing essential is missing for selection.

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% (city, date, min_capacity documented; limit/offset undocumented). The description compensates partially by noting 'filter by city' and 'paginated', but does not clarify limit/offset semantics or min_capacity, so it adds only marginal value over 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+resource with scope: member venues open to receiving a gig request on a date. It distinguishes itself from the broader search_venues sibling and, crucially, declares what it is NOT (room hire / hire rates), so an agent won't confuse it with venue booking tools.

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?

Provides a concrete usage example ('which venues could I pitch for Friday?') and clarifies the request-to-play vs room-hire distinction, which is real routing guidance. It stops short of naming sibling alternatives like search_venues or list_cities explicitly, so it is clear context rather than explicit when/when-not routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuinely new context beyond the structured fields: the listings are "mostly imported, already booked" (data provenance/quality) and results are paginated. It doesn't explain pagination mechanics, hence not 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-loads what the tool returns before usage, then the sibling contrast, then filtering and pagination. Dense but every sentence earns its place with no filler.

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

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

No output schema, but for a read-only search the description covers identity, scope, differentiation, filters, and pagination adequately. It could note return shape or default result ordering, a minor omission.

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 67%, and the schema already documents city, date_from, date_to, and window_days including defaults. The description only echoes filterability by city and date range and repeats the "this weekend" example, adding little semantic detail beyond what the schema provides. Baseline 3 fits.

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 (search gigs) and immediately pins the scope: public listings of shows happening across the UK that are already booked, not work to apply for. It explicitly names the sibling it is not (search_open_gigs), so an agent can distinguish 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 a concrete use case ("what's on in Leeds this weekend?") and states the exclusion rule: gigs open for applications live in search_open_gigs. When/when-not and the alternative are both explicit.

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

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

Annotations already declare read-only, idempotent, and closed-world behavior, so the bar is lower. The description adds useful return behavior (matching articles with their url, or no results when coverage is missing) and warns that mechanics are GigXchange-specific, which helps an agent avoid pulling in outside knowledge.

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 sentences, front-loaded with what is being searched and followed by usage and return behavior. All content is relevant, though the final sentence about platform-specific mechanics is slightly tangential and could 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 simple two-parameter read-only search with full schema coverage and no output schema, the description covers purpose, usage, return format, and scope well. It stops short of routing the agent to get_help_article or list_help_topics for related actions.

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 both query and role are fully documented in the input schema. The description adds no parameter-level detail beyond what the schema already provides, making the baseline 3 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?

Specific verb (Search) and resource (GigXchange's OFFICIAL help articles), with the domain explicitly scoped to platform documentation. It clearly separates itself from non-help search tools, but does not distinguish from the closest siblings get_help_article or list_help_topics.

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 to use it for any 'how does GigXchange work / how do I ...' question, giving clear context. No when-not conditions or named alternatives are provided, so it falls short of the top band.

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, destructiveHint=false, idempotent), so the bar is lower. The description goes further by disclosing output-side traits the annotations cannot: the `id` field needed by apply_to_gig, the `unpaid: true` marker, and the meaning of an empty result. It stops short of return shape or pagination behavior, but the added context is substantive.

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 definition and the routing trigger, and the sentence about the `id`/`unpaid` fields earns its place. Mild redundancy: the search_gigs exclusion is stated twice (once as 'Excludes the imported concert directory' and again as 'concerts in search_gigs are not opportunities').

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 does the work of explaining return-side fields (id, unpaid, budget_unstated) and the empty-result case, so an agent can act on the response. Only pagination behavior and the interaction between limit/offset and date filters remain unaddressed, which is a minor gap for a read-only search tool.

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?

At 67% schema coverage the schema already documents city, date_from, date_to and min_budget in useful detail, including the budget_unstated inclusion rule. The description repeats the budget/unpaid semantics rather than extending them, and says nothing about limit, offset, or how the date window composes. Baseline 3 is appropriate 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 and resource ('Member-posted gigs that are OPEN FOR APPLICATIONS') and immediately scopes it to real venues/promoters with future dates. It explicitly distinguishes itself from search_gigs, the imported concert directory, so an agent can pick between the two 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 concrete user-intent triggers ('what can I apply for?', 'any gigs for me?', 'what work is going in Leeds?') and names the excluded sibling (search_gigs) plus the excluded timeframe (past dates). It even clarifies that an empty result means no opportunities exist, which is exactly the ambiguity an agent would otherwise misread.

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, so safety is covered. The description adds non-obvious behavior: UK-time resolution, pagination, and crucially that a night which does not state kit is recorded in a note rather than treated as 'none' — a real query-semantics quirk not derivable from structured fields.

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, front-loaded with the resource and scope before the parameter nuances. Slightly telegraphic in places ('with day/frequency, signup method, backline and fee'), but every sentence carries information rather than filler.

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

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

With no output schema, the description compensates by enumerating the returned fields and noting pagination. For an 8-parameter read tool with full schema coverage and read-only annotations, this is close to complete; a brief note on default/max page size handling would be the only addition.

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 would be 3, but the description adds meaning beyond the schema: it explains that kit filters match 'as the listing states it' and that unstated kit is not counted as absent, and it clarifies the day parameter's natural-language inputs and UK-time resolution.

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), resource (open mic nights), and scope (recurring, UK, city-level), plus the returned fields (day/frequency, signup method, backline, fee). This lets an agent distinguish it from the singular sibling get_open_mic and from search_venues/search_gigs 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?

Gives concrete selection guidance for the `day` parameter ('open mic tonight / on Thursday', UK time) and for the performer-type and kit filters. It stops short of naming alternatives (e.g. get_open_mic for a single night's detail) or stating when not to use it, so it is clear context but not full routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by clarifying it is 'listings, no booking' and 'Paginated', which tells the agent there is no booking action and that paging is needed for full results.

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 core purpose and returning-resource summary, followed by filters and the sibling pointer. No redundant or filler text.

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 carries return-value burden and does name the key fields plus pagination. For a public read-only directory search this is nearly complete, with only minor gaps (e.g., sort order, total count behavior).

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 all ten parameters including formats and constraints. The description's filter recap ('genre, capacity, PA/backline/engineer and live-music day') restates the schema without adding syntax or edge-case detail. 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: 'public directory of UK grassroots live-music venues in a city.' It also names the returned fields (capacity, backline, PA, engineer, genres booked) and explicitly distinguishes itself from the sibling search_available_venues. An agent can identify this tool without opening the schema.

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

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

It explicitly routes the agent: 'GigXchange MEMBER venues open to a gig request on a date are in search_available_venues.' The scope ('listings, no booking') and the filter set are stated, giving clear selection criteria against the closest alternative.

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 a per-conversation daily quota (10/day), a 2000-character cap, an account-level authorization prerequisite, and the return value (the exact text sent). These are exactly the operational constraints annotations cannot express.

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 that front-load the action and scope, then constraints, then the prerequisite. No filler or repetition.

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

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

For a two-parameter mutation tool with no output schema, the description covers scope, rate limits, size limits, auth requirement, and the return value. 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 both conversation_id and body are already documented, including the 2000-char limit the description repeats. The description adds no syntax, format, or edge-case detail beyond the schema, 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 (send) and resource (text message into a conversation), with an explicit scope boundary: existing conversations only, no new conversations. An agent can distinguish this from any creation or listing sibling 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?

Makes the key selection condition explicit ('EXISTING GigXchange conversations (no new conversations)') and states the prerequisite ('Allow my assistant to act' switch). It does not name a specific alternative sibling tool, but none in the list competes for this action, so the guidance is clear.

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: it delimits the destructive scope (only touches manual entries, never booking-derived ones), explains that a booked night can never be set by hand, and discloses an authorization prerequisite the annotations cannot express. The destructiveHint=true annotation is corroborated and clarified rather than merely restated.

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 dense paragraph, front-loaded with the core action and status list; every clause carries information (status meanings, manual-vs-booking scope, auth prerequisite). It is on the long side and could be split for scanability, but there is little 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 two-parameter mutation with full schema coverage and no output schema, the description covers effect, scope limits, and prerequisites. It omits return/error behavior and what happens when re-setting the same status (relevant given idempotentHint=false), which keeps it just short of complete.

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, but the description adds real meaning: it glosses soft_hold as 'pencilled' and spells out that 'available' clears the manual entry rather than setting one. It does not, however, add anything about the date parameter beyond the schema's YYYY-MM-DD range.

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 (set) on a specific resource (a date on the member's own GigXchange calendar), with the exact domain of the write (availability statuses). The 'own' qualifier and the calendar framing make it distinguishable from read-side siblings like my_availability and check_member_availability 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?

It gives clear usage context: which statuses exist, what 'available' does versus the others, and a hard prerequisite ('Allow my assistant to act' switch under Settings > Integrations > AI). It also rules out hand-setting booked nights, implicitly routing the agent to real booking tools. It stops short of naming a sibling tool or stating explicitly when to prefer this over my_availability.

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 annotations, the description discloses two important behavioral details: the previous bio is returned and included in the member's notification for easy recovery, and the action requires the assistant permission switch. This materially helps the agent understand the destructive action and its recovery path.

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

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

The description is two compact sentences with no wasted wording. The core action and constraints are front-loaded, followed by the recovery behavior and permission requirement.

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

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

For a simple one-parameter mutation tool with annotations covering safety and no output schema, the description supplies the remaining essentials: ownership scope, text constraints, destructive recovery behavior, and permission prerequisite.

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 already 100%, so the schema documents the single bio parameter. The description still adds useful meaning by specifying that the bio is plain text, capped at 1500 characters, and that it is replaced rather than appended.

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/resource pair: 'Replace the member's own public profile bio.' It also scopes the action to the member's own bio and clarifies that it is public, plain text, and constrained to 1500 characters, so the agent can distinguish it from read-oriented profile tools.

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 clear from 'member's own public profile bio' and the prerequisite that the member's 'Allow my assistant to act' switch must be enabled. It does not explicitly compare against alternatives such as my_profile or get_profile, so it is strong context but not full when/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 non-read-only, non-idempotent, destructive behavior, so the bar is lower; the description adds a genuine auth prerequisite (the assistant switch) that isn't in the structured data. It doesn't say whether the write overwrites the prior range outright, which would round this out.

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 clauses with no padding; the mutating action and the target field are front-loaded before the prerequisite. Every element 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?

For a two-parameter mutation with no output schema, the description covers scope, units, and the precondition, while annotations carry the safety profile. The main residual gap is not stating the effect on any pre-existing range or the return behavior, but that is minor here.

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% – both parameters already document units and bounds (max capped at 100000, min >= 0, max >= min). The description only restates 'GBP, min and max', adding no syntax or constraint detail beyond the schema, 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 precise verb+resource: updating the member's own public fee range (GBP min/max) on their profile. The parenthetical '(GBP, min and max)' and 'the same field as the app's profile editor' disambiguate it from read-only siblings like get_rates and profile setters like set_my_bio/set_my_availability.

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 scopes usage to the member's own profile and states the operative precondition ('Allow my assistant to act' switch), which is exactly the kind of context that routes invocation. It stops short of naming an alternative (e.g., get_rates to inspect current values) or an explicit when-not-to-use, so it isn't 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 cover the safety profile (destructive=true, idempotent=true, readOnly=false), so the description's job is to add context. It does: it discloses the side effects (recipient is notified, an invoice card is posted in chat), the automatic refusal of platform invoices, and an auth prerequisite. It does not contradict the destructiveHint=true annotation; it explains the outward-facing action.

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

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

Three sentences, zero filler, and the routing information is front-loaded: what it sends first, the refusal case second, the auth prerequisite last. Each sentence carries distinct decision-relevant content.

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

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

For a one-parameter mutation with no output schema and full annotation coverage, the description supplies everything an agent needs: the eligible invoice type, the side effects on the recipient and chat, the automatic-refusal exclusion, and the permission switch required to act.

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

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

Schema coverage is 100% for the single invoice_id parameter, so the baseline is 3. The description adds meaning beyond the schema by constraining the valid value to the member's own draft settle-privately invoices, matching the schema's note that drafts appear in my_invoices with status draft.

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 (Send) and a narrowly-scoped resource (one of the member's own DRAFT settle-privately invoices) plus the recipient. It explicitly carves out the sibling case — platform-generated booking invoices — so the agent can tell it apart from my_invoices and the automatic platform flow 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?

Gives explicit when-to-use (member's own drafted settle-privately invoice, drafts surfacing in my_invoices) and when-not (platform-generated booking invoices are refused because GigXchange sends them automatically). It also states the precondition — the member's "Allow my assistant to act" switch — which gates the call.

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 flag destructiveHint=true and idempotentHint=false, and 'Toggle' is consistent with that. The description adds a genuine precondition beyond the annotations: the member's 'Allow my assistant to act' switch must be enabled, which the agent needs to know before calling. It stops short of describing failure behavior when the switch is off or what the response contains.

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 short sentences, zero filler, with the operation and its scope stated before the precondition. Nothing could be removed without losing 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 one-parameter toggle whose safety profile is fully covered by annotations, the description supplies the operation, the target scope, and the assistant-permission precondition. It is nearly complete; only the behavior when the precondition is unmet or the return value are unstated, which is minor given the tool's simplicity.

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?

There is one parameter with 100% schema coverage, so the schema already documents 'slug' including its source (search or profile result url). The description's '(by slug)' adds no meaning beyond the schema, 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?

The description states a specific verb (toggle), resource (a GigXchange profile in the member's favourites list), and the selector (slug). It is the only favourites-manipulating tool among the siblings, so an agent can route to it unambiguously 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?

Usage is implied: use it when the member wants to add or remove a profile from their favourites. There is no explicit when-not-to-use guidance and no named alternative, though the sibling list contains no competing favourite tool.

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