discover_hackathon_urls

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

With no annotations, the description carries the transparency burden. It discloses important behavioral traits: search snippets are never presented as events, a candidate only appears after page fetch and evidence of hackathon content, and ingestion stores normalized metadata. This adds useful context beyond the input schema, though it omits potential rate limits or pagination details.

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: it states the main action in the first sentence, then adds necessary behavioral clarifications in the following sentences. Every sentence contributes meaning without unnecessary verbosity.

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?

While the tool's high-level behavior is adequately described, the missing parameter semantics and lack of explicit guidance on when to use this tool over siblings create gaps. The output schema mitigates the need to document return values, but the overall usage context is only partially 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?

Schema description coverage is 0%, yet the description provides no explanation of the 'query' or 'limit' parameters. The agent must infer that 'query' is a search term and 'limit' caps results. This is insufficient given the lack of schema-level 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 clearly states that the tool discovers public event-page URLs via TinyFish Search and then verifies each one. It uses a specific verb ('Discover') and resource ('public event-page URLs'), and it distinguishes itself from siblings like search_hackathons and verify_hackathon_url by describing a combined search-and-verify pipeline.

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 a clear use case: finding and vetting hackathon event URLs. However, it does not explicitly name alternatives or state when NOT to use this tool versus siblings like search_hackathons or discover_public_gallery. The guidance is implied rather than explicit.

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