黑123 Hackathons

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the bar is lower. The description usefully discloses that the response aggregates several secondary collections (official sources, related works, active team posts), which hints at payload size and joins, but says nothing about caching, rate limits, or error behavior for an invalid slug.

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

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

A single sentence that front-loads the verb and resource, then embeds the parameter explanation parenthetically and closes with the return contents. Zero filler and no repetition of the title.

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

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

There is no output schema, so the description correctly compensates by naming what comes back. Combined with the annotations covering the read-only profile, an agent has enough to call this correctly; only edge cases (unknown slug, pagination of team posts) are unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: it defines slug as 'the part after /h/ in the site URL', which is exactly the disambiguation an agent needs to construct a valid value. It adds no format constraints (case sensitivity, length) but the semantic meaning is delivered.

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 hackathon by slug') and immediately scopes it against the sibling search tools by acknowledging it fetches a single entity by identifier. It also enumerates the payload (bilingual details, official sources, related works, active team posts), so an agent can distinguish it from search_hackathons 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?

Usage is implied rather than stated: the slug parameter tells the agent this is a single-record lookup, and the existing slug is the entry condition. However, no siblings are named as alternatives (e.g. 'use search_hackathons if you only have a name'), and there is no explicit when-not guidance.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral detail beyond the schema: fields are bilingual, every result carries its site URL, and dates are UTC YYYY-MM-DD. That materially informs how the agent interprets results.

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

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

Three tight sentences that are front-loaded: what is searched first, then result shape, then the enum semantics that need definition. No redundancy or 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 8 parameters, no required ones, and no output schema, the description carries the return-shape burden well by stating bilingual fields and the presence of a site URL. It could note that no parameters are required and what happens with defaults, but otherwise an agent has enough to call it correctly.

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

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

Schema coverage is 75% and most parameters are already documented, so the baseline is 3. The description goes further by defining the status enum values (upcoming/open/ended) and the date semantics, which the schema lists but never explains.

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 gives a specific verb+resource ('Search hackathons') and names the data source (黑123 / hack123.henryht.sh), so the agent knows exactly what is searched. It does not explicitly contrast itself with the sibling get_hackathon, so it falls short of a 5.

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 nature of the tool and the field semantics, but there is no explicit when-to-use / when-not-to-use guidance or a pointer to get_hackathon for single-record lookups. The status definitions help the agent choose a filter, but routing between siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one useful behavioral fact — expired posts are excluded using the site's own rule — but says nothing about result ordering, pagination, or what a returned post looks like.

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

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

Two tight sentences with the scope stated first and the filtering rule second; nothing is wasted 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?

All parameters are optional and the description covers scope plus the expired-post filter, which is enough to call the tool correctly. It omits pagination/ordering behavior, but with no output schema and strong schema coverage the gap is minor.

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 80% with descriptive text for city, role, query and hackathon, so the schema does most of the work. The description adds no meaning beyond it, which matches the baseline 3 when structured fields carry the load.

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 active team-up posts on the 黑123 /team board, and clarifies they are posts seeking teammates. The resource is clearly distinct from siblings get_hackathon, search_hackathons and search_works, though it never names them explicitly.

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

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

It implies the usage context (finding current teammate-seeking posts) and adds an exclusion rule for expired posts, but offers no when-to-use vs. sibling guidance and no mention of prerequisites or rate limits. Adequate but clearly gapped.

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 openWorldHint=false, so safety profile is covered. The description adds useful context about bilingual tags and the source collection, but does not cover result format, whether results are paginated, or returned fields. Adds some value beyond annotations but not rich 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?

Two sentences, front-loaded with the primary purpose, and the tag example is compact. No wasted words.

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

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

Covers what the tool searches, the source, and bilingual tag semantics, which is sufficient for a read-only search tool with annotations. Missing details about query behavior and result shape, but with no output schema and annotations covering safety, the description is largely complete for invocation.

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

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

Schema description coverage is 75%, so the schema already documents most parameters. The description adds meaningful detail about bilingual tags (e.g., agent/Agent, education/教育学习) and the ability to combine hackathon and tag filters, which supports the tag and hackathon parameters. However, it does not clarify the query parameter or how limit interacts with result counts.

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

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

States a specific verb (search) and resource (hackathon projects/works) with the source (/works on 黑123), and clarifies it is distinct from hackathon search by naming the axis (projects filtered by hackathon and/or tag). The agent can distinguish it from sibling search_hackathons and search_team_posts 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 implies usage through 'by hackathon and/or tag' but does not explicitly say when to use this vs search_hackathons or search_team_posts, nor when not to use it. The context is inferable but not spelled out.

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