extract_public_submissions

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

With no annotations, the description carries the full behavioral disclosure burden. It discloses the dependency on TinyFish, the conditions for live vs cached data, and the guarantee that auth is never bypassed. This goes beyond basic operation and provides meaningful behavioral context, though it omits error cases or rate limits.

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 with the core purpose. Each of the three sentences adds information: purpose, mode selection, and cache/auth behavior. No wasted words or repetition.

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?

Given that an output schema exists and the tool has three parameters, the description covers the key behavioral aspects: live vs cached mode, dependency on TinyFish, and auth safety. It omits details about page_limit and sibling differentiation, but the overall tool context is reasonably complete for selection and 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 0%, so the description must compensate. It adds meaning to use_live_extraction and mentions cached data behavior, but it does not explain page_limit or elaborate on hackathon_id_or_url beyond the schema. It partially compensates for the missing schema descriptions but leaves some parameter semantics unclear.

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 starts with a clear, specific action: 'Extract publicly visible submissions for a hackathon gallery.' This identifies the verb, resource, and scope, and differentiates from sibling tools like list_winning_submissions or discover_public_gallery by focusing on public gallery submissions rather than winners, discovery, or analysis.

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 useful context for parameter choices ('Uses TinyFish when TINYFISH_API_KEY is set and use_live_extraction=True', 'Cached data is available only with use_live_extraction=False'), but it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. It provides clear context but lacks direct guidance among sibling tools.

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