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

Annotations already mark this as read-only; the description adds useful behavioral context beyond that, such as the output fields it returns and the noteworthy rule that hidden events only appear for their own organisers. The minor deduction is that the city/date filtering claim is unsupported by the schema, which is slightly misleading.

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 concise sentences front-load the purpose, then the output value and cross-tool need for the slug, then usage guidance, then an access edge case. Every sentence earns its place and there is 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 usefully enumerates the returned fields and includes an authentication/visibility caveat, so an agent has the essential invocation context. It is slightly incomplete because the city/date filter claim is unexplained and contradicted by the available parameters.

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 fully documents `page`, `status`, and `page_size`, including the important caveat that status filtering happens over the fetched page. The description adds no parameter-level meaning beyond restating 'filter by status, city or date', and the city/date part is not backed by any parameter.

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 — 'Browse hackathons on the platform' — and clearly distinguishes this tool from `search` by noting it returns the slug that other event tools need. However, the claim that you can 'filter by status, city or date' is only partially supported by the schema: only `status` is an actual parameter, so the stated scope is somewhat inaccurate.

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

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

It explicitly says when to use this tool: when the user names an event you do not have a slug for and `search` is not precise enough, or to show upcoming/past events. This gives an agent clear routing guidance relative to `search` and implies that once you have a slug, you should use a different event tool.

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