Crafting Event Finder

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

Annotations only cover the read-only safety profile; the description carries the real behavioral load. It discloses the craft-ignored semantics, child-craft roll-up, the fact that per-craft counts can exceed `total`, the one known discrepancy with craft=<slug> under typo-tolerant search, ordering rules, and explicit 400/503 failure modes.

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?

It is long, but the length is justified by genuine complexity and the information is front-loaded: purpose, then filter contract, then counting semantics, then errors. The opening sentence echoes the title, a small 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?

For a 17-parameter, no-output-schema aggregation tool, nothing essential is missing: filters, dedup/roll-up rules, ordering, total-vs-sum relationship, and error conditions are all covered. An agent could call and interpret this correctly without further sources.

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 0%, so the description must compensate, and it does: it enumerates nearly every filter (q, type, tag, state, when or from+to, near or lat+lng, radius, free, online, inperson, tz) and explains the surprising behavior of `craft`. It omits `sort` and gives no value formats for the string params, so not quite a 5.

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

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

States a specific verb ('count') and resource ('matching events per craft') plus the display purpose ('Jump to a craft' chips). This clearly distinguishes it from the sibling count_events_by_state, which does the same aggregation on a different axis.

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 scopes usage well: it is for chip counts and takes the same filters as GET /api/events, and it explains the craft filter is swallowed rather than applied. It never explicitly names a sibling alternative or a 'use X instead when Y' rule, 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 cover the safety profile (readOnly, non-destructive, closed-world). The description adds genuinely useful behavior beyond them: the 12-month horizon, the published-only filter, and that each state's most common craft is included in the result.

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

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

Three short sentences, front-loaded with the core action, then scope, then the parameter constraint. 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, the description carries the return-shape burden and does so: a per-state count plus that state's most common craft. Filters, time window, and grouping are all covered, leaving nothing essential unspecified for a single-const-parameter read 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?

There is a single parameter whose schema is a const of 'state', so the schema already enforces the value. The description restates '`by` must be `state`', which is redundant with the const but confirms intent for an agent skimming the prose.

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 ('count upcoming events per state') and scopes it precisely with the 12-month window and published-only filter. The name/title and sibling count_events_by_craft make the grouping dimension unambiguous, so an agent can distinguish it from the craft variant.

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 usage through the scope ('upcoming published events in the next 12 months') but never states when to choose this over count_events_by_craft or other list_* tools. Usage is inferable from the name rather than explained.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on caching, freshness, or whether the seasonal value changes over time, which is the one behavior an agent would want to know for a 'season today' field.

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?

It is a single short phrase with no wasted words, which is fine, but it is under-specified rather than genuinely concise — the sentence is essentially a duplicated title and does little more than the name already does.

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 tool with annotations covering safety and no output schema, the description is minimally viable. It still fails to clarify what 'look' and 'season' actually resolve to, which is the main thing an agent would need to interpret the result.

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 document and schema coverage is a moot 100%. Baseline 4 applies for a parameterless 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?

Tautological: description restates name/title.

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

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

There is no guidance on when to call this versus get_site_info, which plausibly covers similar site-level metadata. No prerequisites, exclusions, or alternative routes are mentioned anywhere in the description.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description goes well beyond them: cancelled-but-not-over events still answer with cancelled=true and no upcoming dates, scheduleChange distinguishes postponed/rescheduled/moved-online states, and managedBy is only populated when the organizer profile is public. This is exactly the behavioral context an agent needs before calling.

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

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

Front-loaded with the one-line purpose, and every following sentence covers distinct return/behavior detail that no structured field provides. It is a dense run-on block rather than segmented, but with no output schema the length is earned 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?

With no output schema, the description takes on the burden of explaining the payload and does so well (images/cover, owned, managedBy, cancelled, scheduleChange, previousStartDate, current vs former slug). It omits what happens on an unknown or unpublished slug (error vs empty), which is the one gap for a lookup 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 coverage is 0% for the single slug parameter, so the description must carry it, and it does add real meaning: a former slug (renamed year or town) resolves to the same event and the response returns the current slug. It does not describe slug format or case/encoding expectations, which is the only remaining gap.

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

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

States a specific verb and resource ('Get one event by slug') and scopes it to 'one published event', which implicitly separates it from the list_* siblings. It never names an alternative such as get_not_listed_event or list_events, so the differentiation rests on the reader inferring scope from 'published'.

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 explicit when-to-use or when-not-to-use guidance and no alternative is named, even though the sibling list contains several closely related lookups (get_not_listed_event, similar_events, get_event_join_details). The 'published event' wording hints at scope but is not framed as a routing rule.

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

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

Goes well past the annotations: it discloses the 404 trigger (no name and no email/phone), that this read is rate-limited more strictly than other reads, and that responses carry Cache-Control: no-store and X-Robots-Tag: noindex. These are exactly the operational traits an agent needs and cannot get from readOnlyHint alone.

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 purpose front-loaded and behavioral caveats after. The opening sentence largely restates the title, which is the only minor redundancy; every other clause carries real 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 enumerates the returned fields (name, email, phone, as written by the organizer) and covers failure and throttle behavior. An agent has everything it needs 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?

The single required parameter 'slug' has no schema description (0% coverage) and the description never explains it, beyond implying the tool is event-scoped. With low coverage the description was expected to compensate and it does not.

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+resource ('Get an event's organizer contact') immediately scoped to a distinct slice of event data: the name, email and phone the organizer published. That separates it cleanly from siblings like get_event and get_event_join_details, which cover broader event 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 gives clear context for when the tool applies (you want the organizer's published contact for a specific event) and states the negative condition that produces a 404. It does not name a sibling alternative or an explicit 'use X instead' rule, so it stops 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 only cover the safety profile (readOnly, non-destructive, closed world); the description goes well beyond that by disclosing the concrete data source identifier (crafting-network/event-demand@1), a freshness guarantee ('recomputed at most once a day'), snapshot semantics, determinism/'never depends on the caller', and the fact that only counts and dates are returned. It even documents inclusion/exclusion rules (craft-fair is never a tag, untagged events are dropped) that an agent could not infer 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?

It is long but information-dense: the first sentence states the resource, then scope, then accounting rules, then field semantics, then constraints — a sensible front-to-back order with essentially no filler. The only redundancy is the opening sentence largely restating the title, which costs it the top mark.

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 no parameters, the description carries the full burden of describing the result, and it does so completely: it enumerates every returned field (label, count, online, earliest, regions) and defines each one. No further detail would be needed to interpret a response.

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 of 4 applies. The description usefully makes the no-argument nature meaningful by explaining that the answer is caller-independent and precomputed, rather than leaving the empty schema unexplained.

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 combination ('Upcoming event counts by network craft') and then substantiates it with exact scope (next 60 days, Pacific, per network craft tag from the manifest). An agent can tell what data comes back without opening any schema. It does not, however, distinguish itself from the closely-named sibling count_events_by_craft, leaving a real ambiguity unresolved.

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 explicit when-to-use guidance, and no attempt to route the agent between this tool and the near-identical siblings count_events_by_craft and count_events_by_state. The only usage-adjacent information is the negative constraint that the answer never depends on the caller, which describes determinism rather than selection criteria.

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/non-destructive/closed-world annotations by disclosing the 403 behavior with the details.opensAt field, the 404 case when no details exist, a stricter-than-normal rate limit ('the detail limit'), and cache/robots headers. This is exactly the error- and access-behavior context annotations don't 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-loads the purpose and then stacks constraints, each sentence carrying distinct information. It is dense and slightly run-on (timing, 403, 404, rate limit, headers in one paragraph), but nothing is 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 supplies the return contents, the failure modes, the temporal window, and the caching semantics — everything an agent needs to call this correctly and interpret non-200 responses. The only gap is the unresolved 'slug' parameter, which is a schema-side 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 description coverage is 0% and the single required 'slug' parameter is never mentioned in the description — no format, no source, no distinction from other event identifiers. With low coverage the description is expected to compensate, and it does not.

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 ('an online event's join details') and immediately enumerates what those details are (link, meeting ID, passcode, phone), which distinguishes it from get_event and get_event_contact. An agent can tell exactly what this returns 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?

Gives an explicit availability window — only from 30 minutes before the next occurrence's start until it ends — and what happens outside it (403). It does not name any sibling as an alternative for related data (e.g. get_event or get_event_contact), so routing guidance is strong but not complete.

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

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

Annotations already declare readOnly, non-destructive, closed-world, so safety is covered. The description still adds genuinely useful behavior: 404 for any other slug, a cap of 4 similar events, and an explicit privacy exclusion (never contact, join, or owner details). However it doesn't describe pagination or ordering of the similar events, so this is solid-but-not-rich context on top 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?

Three dense sentences, front-loaded with the returned payload before the applicability rules and the 404 caveat. The opening sentence restates the title almost verbatim, which is minor redundancy but the rest earns its space.

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

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

With no output schema and an undocumented parameter, the description fully carries the burden: it enumerates the return fields (title, cancelled flag, up to 4 similar events), the failure mode, and the privacy boundaries. Nothing an agent needs to invoke it correctly is missing.

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

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

The single slug parameter has 0% schema description coverage, so the description must carry the semantics — and it does, defining the slug as the address of an event the site no longer lists and specifying that all other slug classes yield a 404. It omits format/syntax details (e.g. how slugs are formed), keeping it short of a 5.

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

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

Specific verb+resource: returns the title, cancelled status, and up to 4 similar events for a slug the site no longer lists. It clearly separates itself from get_event (listed events) and similar_events (same search as /similar, referenced explicitly), so an agent can route 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?

Explicit when-to-use (slug of a hidden or cancelled-and-past event) and when-not (unknown, published, or another site's slug returns 404). It also names the alternative behavior by pointing at the /similar search, which is exactly the routing information an agent needs.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, not open-world), so the bar is lower; the description still adds real behavior: the result is ordered upcoming-soonest-first, capped at 50 upcoming then 12 newest past, and 404s for organizers without a display name. It does not discuss any further pagination or rate limits, but for a read-only fetch this is solid.

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 return composition, then the failure condition, in compact sentences with no filler. Every clause (fields, ordering, caps, 404) 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 output schema, the description does the work of describing the return shape—profile fields plus the ordered, capped event lists—and the failure mode, which is thorough for a simple read tool. The only gap is the unexplained slug input, which is the sole required argument.

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 a single parameter (slug) with 0% schema description coverage, so the description carries the burden—yet it never explains what 'slug' is, its format, or how to obtain it. It implies the page is looked up by organizer but adds no semantics beyond that implication.

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 ('Get an organizer's public page') and immediately enumerates the page's contents (name, About, website, town/state, crafts, picture) plus the events it carries. The resource is unique among the siblings (all of which are event/site oriented), so an agent can place 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?

The description gives one useful precondition (only organizers with a display name have a public page; otherwise 404) but offers no explicit when-to-use-vs-alternatives guidance and names no sibling. Usage is implied by the trigger condition rather than 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: no note on what 'crafts' means, whether the call is cached/static, or how results are shaped.

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 short sentence with no filler and the return content front-loaded. It is not padded, though it borders on being too thin to be informative.

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-param read-only lookup, naming what is returned (site name and covered crafts) is the minimum needed. With no output schema, a brief note on the return shape would have helped, but nothing critical is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 is appropriate. The description correctly implies a parameterless, no-input call.

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?

Tautological: description restates name/title.

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 guidance on when to call this versus siblings like get_taxonomy, count_events_by_craft, or lookup_place. There is no stated trigger, context, or exclusion.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that: no statement of whether results are cached, whether the taxonomy is enum-like and stable, or how large the response is.

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?

It is short, but the brevity comes from under-specification rather than efficiency — the single phrase duplicates the title field and carries no independent information. Nothing is front-loaded because there is no real content to order.

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 an output schema absent, the description is the only place an agent could learn what comes back (a list of craft types, event types and tags — flat? grouped? keyed?). That information is entirely absent, leaving the agent unable to anticipate the return shape.

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 and the baseline of 4 applies. No parameter information is missing because no parameters exist.

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?

Tautological: description restates name/title.

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 exclusion criteria, and no reference to any sibling tool. An agent cannot tell from this text whether get_taxonomy supersedes or complements lookup_place, get_site_info, or the count_events_by_* 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 only cover the read-only safety profile, yet the description adds substantial behavior an agent could not otherwise know: invalid filter values are ignored except a no-match near returning 400 validation_failed, location is never inferred from IP, featured events are excluded from items on every page, and featured=0 disables that lookup. This is far beyond what the annotations or schema convey.

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

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

Purpose is front-loaded in the first sentence, and given 20 parameters the density is largely justified with little filler. Structure is weak, though: the filter and location behavior are packed into one run-on paragraph rather than separated, which hurts scanability.

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 20-parameter, zero-required search tool with no output schema, the description is nearly complete, even explaining the featured/items return shape. It omits cursor-based pagination semantics and the limit default, which matter for an agent walking result pages.

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

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

Schema description coverage is only 5%, so the description must carry the load, and it does: it documents q full-text with typo tolerance, taxonomy slug lists with parent/child matching, when enum values, near/lat+lng/radius defaults, free/online/inperson semantics, sort defaults and fallbacks, tz, and trailing-place parsing in q. Only limit and cursor pagination are left unexplained, a minor gap against near-total 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?

States a specific verb and resource ('Search upcoming crafting events on this site') and further scopes it to 'Published, upcoming events with their next date in the window'. This distinguishes it from a plain calendar dump, but it never names or contrasts with siblings like list_online_events or similar_events, so the agent must infer the boundary.

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 is rich in how to use each filter (e.g. online=1/inperson=1 cancellation, radius defaults, q location parsing), which effectively guides invocation. However it gives no explicit when-to-use-this-vs-alternative guidance relative to the many sibling list/count tools, leaving tool selection 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 cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description adds real behavioral context: the exact ranking order, that location is never inferred from IP, and that an unmatched US place in `near` yields a 400. These error and ordering traits go well beyond what the annotations convey, though auth and rate-limit behavior are 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?

Everything is front-loaded in a single paragraph that leads with the tool's purpose, and nearly every clause carries tool-specific meaning. The ranking-algorithm detail is arguably deeper than an agent needs to select or invoke it, but there is no 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?

With no output schema, the description usefully documents the return fields (total, href, matched, crafts) and their derivation, which is real added value. However, for a 17-parameter tool with 0% schema coverage and only read-only annotations, the absence of parameter-level detail leaves an agent guessing at request shapes.

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 are 17 parameters with 0% schema description coverage, so the description carries the full burden. It only says 'Takes the same filters as GET /api/events' – an external reference – and lightly touches tz, near, and the Accept-Language header; it gives no format, units, or allowed values for lat/lng, radius, sort, when, online/inperson, craft, or tag. The compensation is far short of what 17 undocumented params require.

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: return at most 3 online events to show beside a local search, constrained by the search's words, crafts, types, tags, price and dates. This implicitly separates it from siblings like list_online_events and list_events by scoping it to the 'picks band' use case. The dense phrasing costs a little readability but the purpose is discernible 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 gives a usage context ('beside a local search... a place with a distance, or a state'), which implies when to reach for it, but never names an alternative tool or states a when-not condition. An agent must infer that this is the pickup-band companion to a broader events listing rather than being routed explicitly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful non-obvious behavior: a hard cap of 200 events with a `truncated` flag, all filters judged in the viewer's zone, and the fact that events without start times never match a tod filter.

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?

Scope and key behaviors are front-loaded in the first sentence, and the second sentence enumerates filters compactly. The final clause contrasting with GET /api/events is a bit long-winded but still earns its place by preventing a misuse.

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, yet the description discloses the truncation signal and grouping, plus read-only annotations. For a 6-param, zero-required read tool this is largely complete, though return-shape details (fields per event) remain 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%, so the schema already documents tz defaults, tod boundaries, day values, free, lang and craft. The description adds a little rationale (tod/day are computed per event from its own zone, hence living here) but largely restates schema content, so the baseline 3 stands.

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 ('Online events, by day in the viewer's time zone') and scopes it precisely: published online/hybrid events, next 30 days, grouped by the viewer's start date. It differentiates itself from GET /api/events (online=1), which is a strong distinction, though it names an HTTP endpoint rather than the sibling MCP tools like list_events.

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 tells the agent when this tool applies versus the alternative (GET /api/events with online=1) and explains why tod/day filtering lives here. It gives clear usage context but does not name or rule out sibling MCP tools such as list_online_event_picks or count_events_by_craft.

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, non-destructive, closed-world behavior, so safety is covered. The description adds real behavioral detail beyond them: prefix matching against Census data, and a capped, size-ordered result set ('up to 8, largest first').

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 terse clauses, all front-loaded: purpose, matching rule, input format, result contract. Nothing is padded or redundant.

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 discloses the result count and ordering, which is the key contract for a search tool. It stops short of describing returned fields (name, state, population), a minor remaining 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 0%, so the description carries the burden, and it does explain the accepted value shapes ('City' or 'City, ST'). It omits that the string is bounded to 2-60 characters, but the schema enforces that constraint directly.

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

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

States a specific verb and resource ('Look up US places by name') plus the matching mechanism ('Prefix match on US Census places'), which precisely distinguishes it from every event-oriented sibling. An agent knows immediately this is a geocoding/location resolver, not an event 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?

The parenthetical 'for location search' and the accepted input formats give clear context for when to reach for this tool. There is no explicit when-not or named alternative, but no sibling competes for the same job, so the routing risk is minimal.

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?

Adds behavior beyond the annotations by disclosing that requests are reviewed by an admin and never applied on their own, plus the dual authentication paths (Turnstile for browser forms, API key for programmatic callers). This materially affects how an agent should call and reason about the tool, and it does not contradict destructiveHint=false.

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 purpose, then semantics, then auth. No filler, and each 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 covers the key unknowns for a submission-style tool: review/reversibility semantics and the two auth routes. It omits what a caller receives after submitting and any rate-limit or duplicate-submission constraints, but is otherwise complete enough to invoke 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 low (29%), but the description only partially compensates: it clarifies the kind/timing distinction and newStartDate for rescheduled requests, and hints at turnstileToken via the Turnstile mention. It says nothing about slug, message, website, or contactEmail, leaving several parameters undocumented in both places.

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 ('Report an issue with an event listing') and enumerates the concrete issue kinds (wrong, gone, cancelled, postponed, rescheduled). It is clearly distinguishable from siblings like submit_event, which handles creation rather than correction.

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 real usage context: anyone may flag, an admin reviews every request, nothing is auto-applied, and it distinguishes browser (Turnstile) from programmatic (API key) callers. It stops short of naming a sibling alternative or a when-not-to-use condition, so it's strong but not exhaustive.

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 (readOnly, non-destructive, closed-world), and the description adds substantial behavior beyond them: a hard cap of 4 results, never including the source event, distance and date windowing, fallback radius logic, ordering rules, an empty-list case, and 404 behavior for hidden/cancelled/unknown slugs.

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?

Every clause earns its place and the result cap is front-loaded, but the core content is delivered as one very long run-on sentence that is harder to parse than necessary. Density is justified by the complexity, though tighter partitioning into sentences would read better.

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 is responsible for return semantics and it does cover them (up to 4 events, ordering, empty-list case). It omits what fields each returned event contains, but for a recommendation-style tool with full behavioral rules this is only a minor gap.

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

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

Schema description coverage is 0% for the single 'slug' parameter, so the description must carry the load. It implicitly clarifies that the slug identifies an event (via 'never including the event itself' and the 404-on-unknown-slug rule) but never states the parameter's format or that it is the source event's slug explicitly.

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 state a specific resource and behavior: returning up to 4 upcoming events similar to a given event, mirroring the 'More like this' feature. This is clearly distinguishable from siblings like get_event (single fetch) and list_events (browse/filter), so an agent can select 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?

It gives clear context for use ('More like this' on the event page) and fully specifies the matching semantics, which effectively tells the agent what this tool is for. However, it never names an alternative or an explicit when-not condition (e.g. when to prefer list_events or get_event instead), so it falls short of a 5.

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

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

Annotations only give a minimal profile (not read-only, non-destructive, closed-world). The description adds substantial context beyond them: the fate of the submission (moderation queue), the anti-bot/auth paths, submitter recording, the auto-approval/publish behavior for trusted submitters, and a conditional required field. This is rich 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?

Front-loads purpose in the first sentence and dispenses with filler. The final sentence is a sprawling, multi-clause compound that carries a lot of distinct rules and could be broken up, but no sentence is wasted.

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

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

The description is thorough on auth/side-effects for a high-parameter submission tool with no output schema. It leaves the return value (event id, moderation status) unstated and omits semantics for most of the 30 fields, so it is adequate rather than 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 30 parameters and only 17% schema description coverage, the description must compensate, yet it only clarifies organizer_email (optional when signed in, required when anonymous) and implicitly turnstileToken. The vast majority of the 30 fields receive no additional meaning here or in 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?

Specific verb+resource ('Submit an event') with immediate scope clarification ('for review', 'Goes to the moderation queue'). No sibling tool shares this action, and the moderation-queue detail distinguishes it from any read-only event tools in the sibling set.

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 lays out the calling contexts: browser forms use Turnstile, programmatic callers use an API key, signed-in callers skip Turnstile and get recorded as submitter, anonymous callers must supply organizer_email. It gives strong when/how conditions but does not name alternative tools or explicit exclusions.

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