events

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses the auth requirement, a concrete rate limit (max 10/day), and the non-obvious visibility behaviour (unlisted: reachable by URL but absent from catalogue and sitemap). The inclusion semantics of the date range is also stated explicitly, which materially affects behaviour.

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

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

Three dense sentences with zero filler: purpose first, then auth/rate constraints and visibility, then date semantics. Every sentence carries information an agent needs before calling.

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 creation tool with no output schema, the description omits the most consequential return detail: what the caller receives (presumably the new page's URL or an identifier) and whether the page is immediately live. Auth, limits and visibility are covered, but an agent cannot predict the response shape from this text and has no output schema to fall back on.

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

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

Schema description coverage is 60%: start_date, end_date and language are documented in the schema, while name (with min/max length) and description have no schema text. The description only reinforces the inclusive-day semantics of the dates and adds nothing about name or description content, so it does not compensate for the coverage gap; baseline 3 fits.

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

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

The description opens with a specific verb and resource ('Create a public progress page for an event') and immediately qualifies the kind of resource produced. None of the siblings (get_event, search_events, upcoming_events, register_agent) perform creation, so an agent can route here unambiguously; the visibility model (URL-reachable but not in catalogue/sitemap) further pins down what is created.

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 real preconditions for using the tool (API key with a confirmed contact e-mail, 10 per day cap), which is useful scoping. However, it never states when to prefer this over alternatives or what not to use it for (e.g. no guidance on retrieving or updating an event after creation), so usage is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description still adds value beyond that by disclosing what the payload contains: current progress and the provenance of the date verification, which is non-obvious and shapes how the result should be trusted.

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

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

One sentence, no filler, with the identifying key and the notable payload contents both front-loaded. 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 one-parameter read tool with no output schema, the description gives enough about the lookup key and the return contents to call it correctly. Missing only explicit guidance on failure behavior for an unknown slug and on when to prefer a search sibling.

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

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

Schema coverage is 100% and already includes an example value, so the baseline is 3. The description goes further by defining a slug as the last part of the event's URL, which tells an agent how to derive the value from a link rather than only what shape it takes.

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 (retrieve details) and resource (one event) plus the lookup key, so it is clearly distinct from the list-style siblings search_events and upcoming_events. It does not name a sibling explicitly, but the singular 'one event by slug' makes the boundary obvious.

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 slug-based lookup implies when to use it (you already know which event you want), but the description never says so outright and never points to search_events for discovery. An agent must infer the 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?

Beyond the annotations, it discloses the single most important behavioral trait: the key is "shown once, keep it", meaning the value is unrecoverable after the response. It also adds rate-limit consequences and the human-confirmation dependency for contact_email, which the agent would otherwise have to discover by failure.

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

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

Three short sentences, each carrying distinct information — credential issuance, how to use the key, and the email gate — with the critical "shown once" warning front-loaded. Nothing is padding.

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

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

For a two-parameter mutation tool with no output schema, it covers issuance, usage, and the email prerequisite well. It does not say what the response body contains (field name of the key, agent identifier) or what happens if an agent registers twice, which an agent preparing to parse the result would want.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description largely restates the contact_email condition while adding only that a confirmation link is sent. The name parameter gets no added semantic context beyond the schema's own example.

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?

"Issue an API key for your agent" is a specific verb+resource and immediately separates this tool from the event-reading siblings, which do not issue credentials. It does not explicitly name a sibling or state that this is the onboarding step before the event tools, so it stops short of full differentiation.

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 concrete downstream usage ("Send it as Authorization: Bearer <key> on later requests for higher rate limits") and a conditional prerequisite ("Give a contact_email to be able to create events"), which effectively tells the agent when and how this tool's output is used. It lacks explicit when-not-to-use guidance, e.g. whether to skip this if a key already exists.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious behavioral detail: AND-matching semantics across all query words in any order, and the fact that results carry dates, progress, location and a page URL.

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

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

Two sentences, zero waste: the search semantics come first, filters second, return contents last. Nothing is repeated from the schema.

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

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

With no output schema, the description usefully summarizes return fields, and it explains matching rules for a five-parameter search tool. Minor gaps: no mention of pagination/limit behavior or result ordering, which matters for a search tool capped at 25 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 coverage is 100%, so the baseline is 3, but the description meaningfully clarifies query semantics ('every word must match, any order') beyond the schema's example-only description. It also frames status/category/language as optional filters, reinforcing the zero-required-parameter design.

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 — searching curated events by words in the name or description — plus the optional filters. It never mentions the close sibling upcoming_events, so the agent cannot tell from the description alone which of the two to pick when it wants a date-driven browse.

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

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

Usage is implied by the described matching rules and filter list, which implies keyword-driven lookup rather than a general listing. There are no explicit when-to-use / when-not-to-use cues and no pointer to upcoming_events or get_event as alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description contributes the non-obvious fact that results come from a curated catalogue (i.e., a bounded subset, not an exhaustive index) and are ordered by start time. It says nothing about result shape, pagination, or defaults beyond the one in the schema.

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

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

Two sentences, no filler, with the ordering/scope constraint front-loaded before the usage hint. Nothing could be cut without losing information.

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

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

A four-parameter, no-required-parameter tool with 25% schema coverage and no output schema needs the description to explain limit defaults, what category accepts, and what the curated catalogue actually returns. None of that is present, leaving the agent under-equipped to call it well.

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 25%: only within_days is documented (default 90), while limit, category, and language have no descriptions or enumerated values in the schema. The description adds no parameter meaning at all, so it fails to compensate for the coverage gap on three of four params.

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 the resource (events) and its defining scope: soonest-starting, from a curated catalogue, plus the natural-language question it answers. That is more than a restatement of the name. It stops short of naming search_events, so the boundary with that sibling is left to inference.

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

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

"Use it for 'what is coming up?' questions" gives a concrete usage context, which is better than nothing. But there is no when-not guidance and no mention of search_events or create_event, so an agent choosing between an upcoming-list and a search has to guess.

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