Source-attributed events, open data and availability
Scored across 16 tools
Tools are cleanly grouped by domain prefixes (biz_, city_, events_) and each targets a distinct resource or action. Minor overlap exists within events (get vs whats_on, booths vs booth_detail, speakers vs speaker_detail) and between biz_info and biz_menu on menu content, but the descriptions are detailed enough to prevent most misselection.
The dominant pattern is domain_entity in snake_case (biz_info, city_records, events_booths), which is predictable and consistent. The exceptions are events_get and events_list, which use verb-style names, and city_gis, which uses an acronym rather than an entity noun, but these are minor deviations within an otherwise coherent scheme.
At 16 tools the set is slightly above the ideal 3-15 range, but the count is justified by covering three distinct domains: business appointment/menu info, city open data, and event programming. Each tool has a clear role and no tool feels redundant, so the size is reasonable for the connector's scope.
The business workflow is critically incomplete: biz_availability and biz_info explicitly reference biz_book, and biz_menu references biz_order, but neither booking nor ordering tool is exposed in the server. This creates dead ends for the core appointment and pickup-order flows, while the city and event clusters are comparatively complete.
Open appointment slots at a business served through this connector, for one date. date is optional and defaults to today in the business's own timezone. Returns each open slot with a stable slotId that biz_book accepts. Slots that have already started today are never returned, and a day the business is closed returns none with a reason. A business that takes no reservations at all returns no slots and says so, with its opening hours attached. The business may be given by NAME or by id: "Long Beach Brunch Bakehouse" and "longbeachbrunch" both reach the bakery, and a common short form ("the bakehouse", "the dentist") works too. A name we cannot place is refused with the list of businesses we do serve, never answered about a different one.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | YYYY-MM-DD, defaults to today in the business timezone | |
| business | No | Which business, BY NAME OR BY ID. Optional, defaults to velvetandclay. Available: Velvet and Clay (velvetandclay), Brightpoint Dental (brightpointdental), Long Beach Brunch Bakehouse (longbeachbrunch). A common short form works too ("the bakehouse", "the dentist"). A name that does not clearly match one of these is REFUSED with the list, never silently answered about a different business. | |
| businessId | No | Alias for `business`, accepted because every reply carries this name. Takes a NAME OR AN ID, exactly like `business`. Ignored when `business` is also given. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already covering safety, the description adds valuable behavioral detail: date defaults to today in the business timezone, started slots are excluded, closed days return none with a reason, no-reservation businesses return a reason plus opening hours, and unresolvable names are refused rather than silently mapped to another business. This goes well beyond the annotation baseline.
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?
Although the description is long, every sentence contributes essential invocation or edge-case information. It front-loads the core purpose, then covers defaults, return behavior, and name resolution without fluff or repetition of annotation data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains what is returned: open slots with stable slotIds, no-slot and closed-day responses, and opening hours for no-reservation businesses. Combined with the rich input schema, an agent has everything needed to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaning on top: it explains the business parameter accepts a name or id, gives concrete examples, describes the refusal behavior, and clarifies businessId as an alias ignored when business is provided. This is exemplary parameter-level guidance.
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 action and resource: 'Open appointment slots at a business served through this connector, for one date.' It clearly distinguishes itself from sibling tools like biz_info and biz_menu because it is about open reservation slots, not business info or menus.
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 description gives strong context: one date, optional business parameter, and default business behavior. It does not explicitly name alternative tools or say when not to use this one, but the clear focus on appointment slots makes the intended use apparent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Details for a business served through this connector: the business's own one line description (tagline), services or menu with prices, weekly opening hours, the appointment grid length and today's hours. hoursNow is the PRESENT TENSE, already resolved in the business's own timezone: speak its text ("Open now until 2:00 PM", "Closed for today. Hours were 7:00 AM to 2:00 PM") rather than saying a business is open today from a weekday row, which reads as open right now and is wrong the moment the doors shut. Businesses served: velvetandclay (a hair, color and skin studio), brightpointdental (a family and cosmetic dental practice), and longbeachbrunch (an all day breakfast counter, which is WALK IN and takes no reservations). The bookable field on the reply says which is which. velvetandclay and brightpointdental BOTH book into the business's OWN Square calendar (a Square sandbox seller): their availability is read live from Square and booking one writes an appointment there, not into a Sonar database. The schedulingSystem field says so. For a business connected that way the services listed here ARE that seller's own Square catalogue, named exactly as the merchant named them. These are demonstration businesses and the appointment book is a sandbox. Call this first, then biz_availability to see open times, then biz_book to take one. The business may be given by NAME or by id: "Long Beach Brunch Bakehouse" and "longbeachbrunch" both reach the bakery, and a common short form ("the bakehouse", "the dentist") works too. A name we cannot place is refused with the list of businesses we do serve, never answered about a different one.
| Name | Required | Description | Default |
|---|---|---|---|
| business | No | Which business, BY NAME OR BY ID. Optional, defaults to velvetandclay. Available: Velvet and Clay (velvetandclay), Brightpoint Dental (brightpointdental), Long Beach Brunch Bakehouse (longbeachbrunch). A common short form works too ("the bakehouse", "the dentist"). A name that does not clearly match one of these is REFUSED with the list, never silently answered about a different business. | |
| businessId | No | Alias for `business`, accepted because every reply carries this name. Takes a NAME OR AN ID, exactly like `business`. Ignored when `business` is also given. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
This description goes far beyond the readOnlyHint annotation by explaining that hoursNow is present-tense and timezone-resolved, warning against interpreting weekday rows as 'open now,' and disclosing the Square sandbox/demonstration context engagement behavior. It also clearly states how unrecognized business names are refused rather than silently matched, which is critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but densely informative: core fields, present-tense warning, business roster, Square context, pipeline, and name resolution are all covered in a logical order. A little trimming of the downstream booking details would tighten it, but the structure is appropriate for the connector's complexity.
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 names all key returned fields (tagline, services/menu, hours, appointment grid length, hoursNow, bookable, schedulingSystem) and provides the exact workflow with biz_availability and biz_book. It also covers all three supported businesses, name resolution, and the refusal fallback, so nothing needed to call biz_info correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both business and businessId with 100% coverage, including name-or-id resolution, defaults, and short-form behavior. The description adds examples and repeats the resolution/refusal semantics, but it does not materially change or add parameter meaning beyond what the schema already provides.
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 states what biz_info returns—tagline, services/menu with prices, weekly hours, appointment grid length, and today's hours—so an agent knows what resource and data are involved. It doesn't explicitly contrast a sibling like biz_menu or biz_availability in the purpose statement, but the field list and 'Call this first' pipeline make the tool's role clear.
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 description explicitly gives a workflow: 'Call this first, then biz_availability to see open times, then biz_book to take one,' which tells the agent when in the overall flow to use this tool. It does not directly address excluding siblings like biz_menu, but the sequencing and refusal behavior provide strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FOUNDER PREVIEW, NOT A PUBLISHED FEED. Upcoming public events run by the City of Long Beach: library programmes, parks and recreation, animal care clinics, city clerk and council sessions, hazardous waste collection, economic development workshops and more. Read from the calendar publisher's own JSON feed rather than scraped from a page, and every response says so. The City has NOT STATED A LICENSE for this data, so Sonar Connections does not list it publicly and it appears on no indexable page, sitemap or llms.txt; it is served here for founder evaluation only, pending a written partnership with the City. Times are returned exactly as the City publishes them, as local wall-clock strings with the UTC offset beside them, and are never converted. Cancelled events are RETURNED and clearly marked rather than hidden, because a cancelled event is the answer to "is it on tonight".
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | How many days ahead to read, 1 to 60 (default 14) | |
| limit | No | Events to return, 1 to 50 (default 10) | |
| search | No | Match a word across event title, description, location and department | |
| department | No | Filter by city department or calendar, e.g. "Long Beach Public Library" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=true, and the description adds substantial behavioral context beyond that: it discloses licensing uncertainty, non-publication status, timezone handling (local wall-clock with UTC offset, never converted), and the notable behavior of returning cancelled events rather than hiding them. This is rich, honest behavioral disclosure.
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 longer than average, but every sentence carries meaningful information: preview status, data source, licensing, timezone behavior, and cancelled-event handling. It is front-loaded with the most important caveat (FOUNDER PREVIEW). Slightly verbose but each sentence 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 read-only calendar tool with 100% schema coverage and no output schema, the description covers the essential context: what data it reads, how times are formatted, how cancellations are handled, and the legal/publication status. An agent has everything needed to decide whether to call it and interpret results.
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 four parameters. The description adds context about the data source and time handling but doesn't add meaning to the parameters themselves beyond what the schema provides. 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?
The description names a specific resource (Long Beach public events calendar), a specific verb (read), and enumerates the event categories covered. It also distinguishes itself from scraped feeds by stating it reads from the publisher's own JSON feed, which helps separate it from sibling event 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 description clearly states this is a founder preview, not a published feed, and explains when it should be used (for evaluating upcoming City of Long Beach events). It doesn't explicitly name sibling alternatives or say when not to use it, but the preview status and data-source distinction provide clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The open data catalog of one public data source: every dataset with its id, title, description, record count, last-modified date and license. Call this first to discover which dataset ids city_records accepts. source is optional and defaults to "longbeach" (the City of Long Beach portal, DataLB). Every response names its source.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | Data source id, e.g. "longbeach" (default) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful behavioral details beyond the schema: it returns every dataset with specific fields, is scoped to 'one public data source,' and notes 'Every response names its source.' These details help an agent anticipate the response shape and source 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?
The description is only two sentences but packs in the tool's purpose, output fields, the source default, and its role in the city_records workflow. Every sentence earns its place, and the most important usage directive is front-loaded in the second sentence without being 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 compensates by listing the exact fields returned and the source-naming behavior. It also clarifies the tool's role as a prerequisite for city_records, addresses the optional parameter's default, and provides enough guidance for an agent to call it correctly. There are no critical gaps.
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 sole parameter, so the baseline is 3. The description mostly repeats what the schema already tells us: that 'source' is optional and defaults to 'longbeach'. The added phrase about the City of Long Beach portal is contextually helpful but does not meaningfully change an agent's understanding of the parameter 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 and resource: it lists the open data catalog, enumerating exactly which fields are returned (id, title, description, record count, last-modified date, license). It also distinguishes itself from city_records by explaining it is the discovery-first step that supplies dataset ids. This is far beyond a vague or tautological statement.
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 description explicitly says 'Call this first to discover which dataset ids city_records accepts,' which gives clear when-to-use guidance and names the natural follow-up tool. It does not enumerate exclusions for other siblings, but it provides enough context to route an agent correctly for the discovery workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FOUNDER PREVIEW, NOT A PUBLISHED FEED. Search and read a city GIS, a public ArcGIS organization of map layers covering parcels, zoning, districts, bikeways, parks, neighborhoods, permits and more. SOURCES: longbeach (City of Long Beach, 174 public layers listed) and huntingtonbeach (City of Huntington Beach, 113 servable of 121 listed; the other 8 are hosted on the City's own server, which this connector does not read). Pass source to choose; it defaults to longbeach. Each answer names the city it came from, and a search answer says how many results it refused and why. Each publisher has NOT STATED A LICENSE for this data, so Sonar Connections does not list it publicly and it appears on no indexable page, sitemap or llms.txt; it is served here for founder evaluation only, pending a written partnership with the publisher. HOW TO USE IT: call with search to find layers by topic and get their item ids, then call with item_id AND THE SAME source to read one layer. Reading a layer returns its field schema, its row count and a capped sample of rows; add filter to match a word across the layer's text fields. WHAT IT WILL NOT DO: it never returns raw geometry, so a polygon layer answers which, where and how many rather than emitting coordinates. Any layer whose field names look like they describe individual people (owner or applicant names, home addresses, plates, dates of birth), and any Survey123 response layer whatever its columns are called, returns its schema and counts only, never rows, and says what triggered that. The screen is conservative and can fire on a layer that only describes places, which is why it reports its reasons.
| Name | Required | Description | Default |
|---|---|---|---|
| layer | No | Layer index within the service (default 0) | |
| limit | No | Results to return, 1 to 50 (default 10) | |
| filter | No | Match a word across the layer text fields, e.g. a street or a name | |
| search | No | Find layers by topic, e.g. "zoning", "parks", "bike" | |
| source | No | Which city GIS: "longbeach" or "huntingtonbeach" (default longbeach) | |
| item_id | No | ArcGIS item id from a search result, to read that layer |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already say readOnlyHint and openWorldHint, the description adds substantial behavioral context: it is a founder preview pending licensing, it returns schema/row-count/capped sample, it never returns raw geometry, it privacy-screens person-like fields and Survey123 layers and reports refusals, and the screen can be conservative. This far exceeds the annotation bar and gives an agent accurate expectations for call outcomes.
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 long and somewhat repetitive ('FOUNDER PREVIEW, NOT A PUBLISHED FEED' and later 'it is served here for founder evaluation only'). However, it is well-structured with explicit 'HOW TO USE IT' and 'WHAT IT WILL NOT DO' sections, and it front-loads the purpose. Some sentences could be tightened without losing information, so it earns a 3.
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 tool with no output schema, the description covers the necessary context: what the search returns, what reading a layer returns, the geometry restriction, privacy filter behavior, refusal reporting, and licensing limitations. It does not mention rate limits or timeouts, but for its complexity it 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?
With 100% schema description coverage, the baseline is 3. The description goes beyond the schema by explaining the two-phase workflow (search returns item_id; item_id must be paired with the same source), describing what `filter` matches across text fields, and noting that `source` defaults to longbeach. It adds real semantic value that the schema alone does not convey.
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 opens with a specific verb-resource pair: 'Search and read a city GIS, a public ArcGIS organization of map layers,' and enumerates coverage (parcels, zoning, districts, bikeways, parks, neighborhoods, permits). This clearly sets it apart from the sibling tools like city_calendar or events_list. It does not explicitly name a sibling or contrast with city_datasets/city_records, which would be needed for a 5, but the GIS focus is unmistakable.
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 description gives explicit workflow guidance: first call with `search` to get item ids, then call with `item_id` and the same `source` to read a layer. It also explains the default source and when to pass `source`. However, it never tells the agent when to prefer this tool over a sibling like city_datasets or city_records, so it lacks explicit exclusions/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one PAGE of records from a public open dataset. Give a dataset_id from city_datasets, an optional full-text search, an optional limit (default 10, maximum 50) and an optional offset to page through larger result sets. Datasets can hold hundreds of thousands of records, so a full page is usually NOT the whole answer: the response carries truncated, matchingRecords and a nextOffset to call back with. source is optional and defaults to "longbeach" (the City of Long Beach portal, DataLB). Returns the dataset schema plus the records, and names its source.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return, 1 to 50 (default 10) | |
| offset | No | Rows to skip, for paging. Use the `nextOffset` from a previous call. 0 to 1000; deeper paging is not served (download the full file from the city portal instead). | |
| search | No | Optional full-text search across the records | |
| source | No | Data source id, e.g. "longbeach" (default) | |
| dataset_id | Yes | Dataset id from city_datasets, e.g. "service-requests" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint), the description discloses paging semantics ('a full page is usually NOT the whole answer'), the response fields (truncated, matchingRecords, nextOffset), and the offset limit (0 to 1000) with an explicit alternative. It also states the return includes dataset schema and records, adding transparency not available elsewhere.
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 rich but every sentence earns its place: purpose, parameters, paging warning, return structure, and source. It is front-loaded with the core action and efficiently packs needed details without 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?
Given the complexity (paging, source default, return structure) and the absence of an output schema, the description fully equips an agent to call the tool correctly. It covers paging, limits, source, and what is returned, leaving no critical 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 coverage is 100%, so the baseline is 3, but the description adds value by noting defaults (limit default 10, maximum 50) and the paging role of offset, plus the source default to 'longbeach'. This goes beyond the schema's raw descriptions.
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 opens with a specific verb and resource: 'Read one PAGE of records from a public open dataset.' It clearly distinguishes the tool from its siblings by referencing city_datasets for dataset_id and explaining the paging behavior, which sets it apart from dataset-listing 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 explicit context on when to use it (paging through large datasets) and an alternative for deeper paging: 'download the full file from the city portal instead.' It also instructs to use dataset_id from city_datasets, which is a clear prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FOUNDER PREVIEW, NOT A PUBLISHED FEED. Street sweeping schedules for the City of Long Beach, read live from the City of Long Beach GIS (a public ArcGIS feature service). The City has NOT STATED A LICENSE for this data, so Sonar Connections does not list it publicly and it appears on no indexable page, sitemap or llms.txt; it is served here for founder evaluation only, pending a written partnership with the City. WHAT THE DATA ACTUALLY IS: 336 schedule POLYGONS whose only attributes are DAYS (e.g. "Tuesday/Wednesday", "Friday") and HOUR (e.g. "8-10a", "1230-230p"). There is no street name, no street side, and no route or week number in the layer, so a street lookup is answered by intersecting the City's own street centerlines with the zone polygons, and the answer names the zones a street runs through rather than one schedule per address. Two-day values are reported as published: the City does not state whether they mean both days or one side of the street per day, and this tool will not guess. Call with street, with day, with both, or with neither to see every schedule the City publishes. Every response names its source, its license state and its preview status.
| Name | Required | Description | Default |
|---|---|---|---|
| day | No | Day filter, e.g. "Tuesday". The published data covers Monday to Friday only. | |
| limit | No | Distinct schedules to return, 1 to 25 (default 10) | |
| street | No | Long Beach street name, e.g. "Pine Ave" or "East Ocean Blvd". Resolved against the City street centerline layer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, and the description substantially expands on this with source, license state, preview status, and interpretation caveats. It discloses that the underlying layer lacks street names and sides, that two-day values are ambiguous, and that street lookups are done via centerline intersection. This is far beyond what annotations provide.
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 long, but every block earns its place: preview/license warning, data shape, lookup semantics, ambiguity caveat, and invocation patterns. It is front-loaded with the most important operational caveat ('FOUNDER PREVIEW') and uses clear section markers. It could be tightened slightly, but it is structured and dense rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with zero required parameters, no output schema, and substantial data caveats, the description is remarkably complete. It explains what the data actually contains, how street lookups behave, what the tool will not do, and what every response will include. An agent has enough context to invoke it correctly and interpret results without further exploration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters. The description adds meaningful semantics: street lookups are resolved by intersecting the city centerline layer, day filters cover Monday–Friday, and two-day values are reported as published without guessing. The 'limit' parameter is not mentioned in the description, but the schema covers it.
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 states the tool returns Long Beach street sweeping schedules read live from the City's ArcGIS feature service. It names the specific verb ('read'), the resource ('Long Beach GIS'), and the exact data domain, which distinguishes it from sibling city_gis/city_datasets/city_records tools. The scope is unambiguous.
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 description gives concrete invocation patterns: 'Call with `street`, with `day`, with both, or with neither to see every schedule the City publishes.' It also explains the founder-preview context and that the tool will not guess ambiguous two-day values. It does not explicitly compare against sibling tools, but the use context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full public card for one booth: description, menu items with ticket prices where present, products (what the vendor sells, as the booth sheet in the app lists it), the printed aisle, public links, logo and today's offering if set. mapless: true means the booth has no position on the floor plan. Accepts a booth id or a booth/vendor name.
| Name | Required | Description | Default |
|---|---|---|---|
| boothNameOrId | Yes | Booth id (stall_frosted_cupcakery) or name | |
| eventIdOrSlug | Yes | Event id (belmont_stroll), public slug (cba26), or the event NAME as events_list spells it ("Summer Stroll & Savor"). Common short forms work too ("the stroll", "tie summit"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already present, the description still adds meaningful behavioral context: it explains the meaning of `mapless: true`, notes that menu ticket prices appear only 'where present', and clarifies that `products` is the vendor goods list from the app's booth sheet. This goes beyond the annotations without contradicting them.
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 three compact sentences with no filler. The most important information (what the tool returns) is front-loaded, and each sentence earns its place: contents, special flag meaning, and accepted inputs.
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?
Despite lacking an output schema, the description enumerates the key response fields and defines the `mapless` flag, giving an agent enough understanding of what to expect. For a simple read-only lookup with two fully documented parameters, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully documented in the schema (100% coverage), and the description essentially restates that a booth id or name and an event id/slug/name are accepted. It adds no new semantic detail beyond what the schema already provides, so the 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?
The description clearly states the tool's purpose: 'The full public card for one booth' with a detailed list of contents. It distinguishes itself from the sibling list tool events_booths by emphasizing a single booth and specifying accepted inputs (booth id or name).
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 description gives clear usage context: this tool returns the full detail card for a single boothcookie, and explains that it accepts either a booth id/name and an event id/slug/name. It does not explicitly contrast it with alternatives like events_booths or state when not to use it, so it falls just 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.
Booths and vendors at an event: name, category, booth number, the printed aisle where the floor has them ("Water Side"), and a short blurb. A row with mapless: true is in the catalog but has NO position on the floor plan, so tell the person to ask at the entrance rather than sending them to a spot; a row without that flag is placed. Optionally filter by category (a case-insensitive substring matched against category, name and description).
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Optional category filter, e.g. "dessert" | |
| eventIdOrSlug | Yes | Event id (belmont_stroll), public slug (cba26), or the event NAME as events_list spells it ("Summer Stroll & Savor"). Common short forms work too ("the stroll", "tie summit"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=false, which are consistent with the description (listing data). The description goes beyond annotations by explaining the semantic meaning of the mapless flag and instructing the agent to advise asking at the entrance, which is crucial behavioral context for handling results. It also clarifies that filtering matches against multiple fields case-insensitively. No contradiction; adds meaningful operational detail.
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 moderately long but each sentence serves a purpose: the first states the output fields, the second explains a critical data nuance (mapless), and the third covers the filtering behavior. It is front-loaded with the primary purpose and then adds specifics. It could be trimmed slightly, but the information density is high and relevant.
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 tool with only 2 parameters and no output schema, the description adequately conveys the return content (fields, mapless semantics) and filter behavior. It does not explicitly explain the response structure (e.g., array vs object), but for a listing tool this is usually inferable. The mapless guidance is especially complete for handling edge cases. Slightly more detail on pagination would be nice but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the category filter is a case-insensitive substring matched against category, name, and description—information not fully captured in the schema's terse 'Optional category filter'. This helps the agent formulate effective queries and interpret results.
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 states the verb 'List' and the resource 'booths and vendors at an event', and enumerates the exact data fields returned. This distinguishes it from siblings like events_get or events_whats_on by focusing on the booth/vendor domain, and from events_booth_detail by indicating it handles the collection rather than a single detail.
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 description establishes the clear context of when to use this tool (when booths/vendors are needed) but does not explicitly name alternatives or exclusions such as 'for event schedule use events_whats_on'. The resource specificity implies usage, but there is no explicit guidance about when NOT to use it. This meets 'clear context, no exclusions'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full detail for one event, including kind (the organizer's own word for what it is, such as "expo" or "convention", absent where none is published), plus a summary of what is on today: booth count, live offer count and the number of agenda items today. Accepts the event id or its public slug.
| Name | Required | Description | Default |
|---|---|---|---|
| eventIdOrSlug | Yes | Event id (belmont_stroll), public slug (cba26), or the event NAME as events_list spells it ("Summer Stroll & Savor"). Common short forms work too ("the stroll", "tie summit"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already signaling safe read-only behavior, the description adds useful context: the 'kind' field is absent when not published, and the response includes a dynamic 'today' summary with booth, live offer, and agenda counts. This goes beyond the annotations without contradicting them.
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 compact and front-loaded with the core purpose ('Full detail for one event') followed by useful clarifying details about response contents and identifier formats. It is slightly dense in a single sentence but 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 single-parameter read-only tool with no output schema, the description covers the key return aspects (kind plus today's summary counts) and identifier acceptance. It does not enumerate all 'full detail' fields, but that is not necessary for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter description already thoroughly documents accepted forms: id, slug, event name, and common short forms. The tool description restates only 'event id or its public slug', adding no real semantic value beyond what the schema provides, 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 title and description clearly identify this as retrieving full detail for a single event, with a specific verb ('Get') and resource ('one Sonar event'). It distinguishes itself from sibling list tools like events_list and specialized detail tools like events_booth_detail by focusing on the event as a whole.
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 description implies use when a caller needs full event detail and already has an identifier, and the parameter documentation explicitly references events_list as the source for event names. It does not explicitly name alternatives or state when not to use this tool, so it misses the top bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Sonar Connections events available through this connector: id, slug, name, venue or city, dates, description and kind (the organizer's own word for what it is, such as "expo" or "convention"; absent on events that publish none, and never guess one). Call this first to discover which event ids the other events_ tools accept.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral nuance beyond the readOnlyHint annotation by explaining the `kind` field: it is the organizer's own word, may be absent, and should never be guessed. This helps the agent interpret results correctly. It does not mention potential pagination or rate limits, but with zero parameters and a read-only list, this is a minor gap.
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 entire description is one well-structured sentence that front-loads the action, lists the key fields, and then adds the critical caveat about `kind`. Every phrase earns its place, and the 'Call this first' instruction is a valuable closing directive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool, the description is complete: it explains what is returned, the semantics of a tricky field, and how the tool fits into the larger events_ workflow. No output schema exists, so the field list and 'discover ids' note fully cover what an agent needs to call and use this 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 has no parameters, so there is nothing to document. The description instead clarifies output fields, which is useful. Baseline 4 is appropriate for a zero-parameter tool.
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 begins with a specific verb and resource: 'List the Sonar Connections events available through this connector', and enumerates the fields returned. It also differentiates the tool from sibling events_ tools by positioning it as the entry point for discovering event IDs.
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 description gives explicit usage direction: 'Call this first to discover which event ids the other events_ tools accept.' This clearly states when to use the tool. It does not explicitly list conditions for when not to use it, but the guidance is strong enough for an agent to know this is the initial discovery step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Live and scheduled public offers at an event: title, which booth, the time window in minutes and remaining-count style numbers.
| Name | Required | Description | Default |
|---|---|---|---|
| eventIdOrSlug | Yes | Event id (belmont_stroll), public slug (cba26), or the event NAME as events_list spells it ("Summer Stroll & Savor"). Common short forms work too ("the stroll", "tie summit"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds useful behavior beyond that: it returns only live/scheduled public offers and specifies the output fields (title, booth, time window in minutes, remaining-count style numbers). It does not mention ordering, limits, or pagination, but it discloses the core return shape.
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 one compact sentence with no redundancy. It front-loads the core scope ('Live and scheduled public offers at an event') and then packs the essential output detail, earning every word.
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 list operation with no output schema, the description adequately covers what is returned and the event context. Minor omissions like sort order or result limits are not critical given the input schema fully documents the event identifier.
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 single parameter's accepted formats are already fully documented in the schema. The tool description adds no additional parameter semantics, which matches the baseline for high schema coverage.
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 (public offers) and a clear time scope (live and scheduled), which distinguishes it from broader siblings like events_list and events_whats_on. It does not explicitly name or differentiate against a sibling, but the verb-plus-resource is still clear.
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: this tool lists offers tied to an event and requires an event identifier. There is no explicit statement about when to prefer this over events_booth_detail or events_whats_on, nor any 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything an event publishes about one person on its programme: their job title line, role (a speaker-level note such as "Moderator"), company, bio, expertise tags, public social links, a portrait, a link to the organizer's own profile page, and every session they are on with the spoken local time. Accepts a name or a speakerId. If the name is not clear enough to be sure - two people sharing a surname, say - the reply is a not-found carrying the closest names rather than a guess, so ask the person which one they meant. Absent fields are null: the organizer published nothing there, so say nothing rather than filling the gap.
| Name | Required | Description | Default |
|---|---|---|---|
| speaker | Yes | A speaker name ("Aasif Mandvi", or just a surname) or a speakerId as events_speakers returns it | |
| eventIdOrSlug | Yes | Event id (belmont_stroll), public slug (cba26), or the event NAME as events_list spells it ("Summer Stroll & Savor"). Common short forms work too ("the stroll", "tie summit"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses two important behaviors: ambiguous names produce a not-found with closest names (rather than a guess), and absent fields are null (rather than omitted or fabricated). These are non-obvious and help an agent set user expectations accurately. It does not contradict the annotations; it adds complementary detail.
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 longer than typical, but each sentence earns its place: the first enumerates the response content, the second covers accepted inputs, the third explains ambiguity handling, and the fourth defines null semantics. It is front-loaded with the core purpose, and there is no filler. A slightly tighter phrasing could remove redundancy, but the structure is purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only detail tool with two parameters and no output schema, the description covers what is returned (the full field list), how inputs work, how ambiguity is handled, and how absent fields are represented. It does not describe edge cases like event/speaker not found independently, but the ambiguous-name not-found behavior covers a key failure mode. Overall, an agent has enough context to call the tool correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by stating that 'speaker' can be a name or surname or a speakerId as returned by events_speakers, and that 'eventIdOrSlug' accepts common short forms ('the stroll'). This helps an agent map natural-language input to the correct parameter format.
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 opens with a specific verb and resource: 'Everything an event publishes about one person on its programme.' It enumerates the exact fields (job title, role, company, bio, expertise tags, social links, portrait, organizer profile link, sessions with local time), and clearly distinguishes itself from the sibling events_speakers by focusing on a single person. An agent immediately understands this is a detail lookup for one speaker.
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 description clarifies accepted inputs (name or speakerId, event ID/slug/name) and gives concrete disambiguation guidance: if the name is ambiguous, the tool returns closest names instead of guessing, and the agent should ask the user which one. It doesn't explicitly say 'use this instead of events_speakers when you need a single speaker's details,' but the singular focus and reference to events_speakers provide strong implicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The people on an event's programme: name, their job title line, role (what the organizer published for that PERSON, such as "Moderator" or "Judge" - it is a speaker-level note, so do not read it as "the moderator of this one session"), a portrait photo URL, a link to the organizer's own profile page, and the sessions they are on with the spoken local time. Ordered by when they are first on stage. Optionally filter to one day. Any field except the name may be null, which means the organizer published nothing there: say nothing rather than filling the gap. When an event publishes no speaker records the roster is built from the programme itself and source says "program"; those rows carry a kind of "speaker" or "performer" and nothing else about the person.
| Name | Required | Description | Default |
|---|---|---|---|
| day | No | Optional day filter: "today" or YYYY-MM-DD, read in the event's own timezone | |
| eventIdOrSlug | Yes | Event id (belmont_stroll), public slug (cba26), or the event NAME as events_list spells it ("Summer Stroll & Savor"). Common short forms work too ("the stroll", "tie summit"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already declared, the description still adds substantial behavioral context: null-field semantics, the distinction between role as a speaker-level note and a session role, ordering by first stage appearance, and the program-derived roster behavior with source and kind values. This goes well beyond the annotation baseline and contains no contradiction.
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 dense but every sentence earns its place: field list, ordering, filtering, null behavior, and fallback construction. No filler or repetition of schema details, and the most important scoping information is front-loaded.
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 full burden of describing return values, ordering, null handling, and edge cases. It covers all of these clearly, and the only remaining ambiguity—how this relates to events_speaker_detail—is a sibling differentiation matter rather than a completeness gap for calling the 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?
Schema description coverage is 100%, so the schema already documents both parameters fully, including the day filter timezone semantics and the flexible eventIdOrSlug forms. The description only echoes 'Optionally filter to one day' without adding new parameter-level meaning, 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 and resource: listing the people on an event's programme, with a detailed breakdown of returned fields. It is clear and unambiguous, but it never explicitly distinguishes itself from the sibling events_speaker_detail, so an agent must infer the boundary between 'all speakers for an event' and 'one speaker's detail'.
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 description provides clear situational context: it is for retrieving an event's speakers, supports optional day filtering, and explains the fallback when no speaker records exist. It does not, however, state when to prefer this tool over alternatives like events_speaker_detail or events_whats_on, so exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Agenda sessions and performances with their times. when accepts "all" (default), "today", "now" (the next few hours) or a YYYY-MM-DD date. Each row carries a speakers array in the order the session lists them, with each speaker's name, role (what the organizer published for that PERSON - "Moderator", "Judge" - it is a speaker-level note, so do not read it as "the moderator of this one session"), title (their job title line, which is a different fact from role and both may be present), company, bio, expertiseTags, socialLinks, a portrait photo URL, and a link to the organizer's own speaker profile page. Any of these except the name may be null or absent, which means the organizer did not publish it: say nothing rather than filling the gap. speakerNames is still there for the plain lineup.
| Name | Required | Description | Default |
|---|---|---|---|
| when | No | "all" | "today" | "now" | YYYY-MM-DD | |
| eventIdOrSlug | Yes | Event id (belmont_stroll), public slug (cba26), or the event NAME as events_list spells it ("Summer Stroll & Savor"). Common short forms work too ("the stroll", "tie summit"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnlyHint annotation by detailing the exact output structure: the `speakers` array fields, null handling (say nothing rather than filling gaps), and the critical distinction that `role` is a speaker-level note, not a session moderator. It also explains the `when` parameter semantics. This provides actionable guidance for interpreting results correctly.
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 long but dense with necessary information because there is no output schema. It front-loads the core purpose, then explains `when`, then details the speaker structure. Each sentence serves a purpose, particularly the role clarification and null handling. It is appropriately sized for the complexity, though slightly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested return structure and no output schema, the description covers all essential aspects: agenda contents, speaker fields, null semantics, and the `when` filter. It is complete for an agent to select and invoke correctly, and to interpret results without surprises. The readOnlyHint covers safety, and the description fills the rest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds explicit meaning to the `when` parameter (all, today, now, date) and clarifies the default, which is valuable. For `eventIdOrSlug`, the schema already provides detailed guidance, so the description adds nothing new there. The extra `when` detail raises it to a 4.
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 states it returns 'Agenda sessions and performances with their times', which is a specific verb+resource definition. It distinguishes from siblings like events_list (lists events) and events_get (gets event details) by focusing on the agenda/lineup within an event. The title 'Get the agenda or lineup' reinforces this.
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 description explains the `when` parameter and its values, giving context on how to filter. However, it does not explicitly mention when to use this tool vs alternatives like events_speakers or events_speaker_detail, nor does it state any exclusions. The purpose is clear enough to infer usage, but explicit comparison is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
biz_availabilitybiz_infobiz_menucity_calendarcity_datasetscity_giscity_recordscity_sweepingevents_booth_detailevents_boothsevents_getevents_listevents_offersevents_speaker_detailevents_speakersevents_whats_onGlobal tsunami events from NOAA NCEI, 2000 BC-present: wave height, runups, and counts.
Global earthquake events from the USGS, 2150 BC-present: magnitude, depth, location, counts.
Global flood events and extent 1985-present from the Dartmouth Flood Observatory and GFD.
Scholarly literature search across nine sources
Add one secure layer between your agents and this server.