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

With no annotations available, the description carries the full behavioral disclosure burden, and it does so thoroughly. It explains the exactly-once, no-gaps/no-repeats cursor semantics, the 24-hour default, the event payload content (event type, timestamp, diff, job record), and the filtering behavior. This is rich, honest behavioral context beyond what any schema could infer.

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 dense but every sentence earns its place. It front-loads what the tool returns, then explains the polling protocol, filtering, payload details, and use cases in a logical order. No filler or repetition exists, and the length is justified by the tool's complexity.

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 an 11-parameter tool with no annotations and a real output schema, the description covers almost everything an agent needs: how to start polling, how to continue polling, what each event contains, how to filter, and when to use the tool. The output schema can handle detailed return shapes, so the description is complete without over-explaining.

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 55%, and the description adds meaningful semantics for key parameters: since is for the first poll, cursor is meant to be passed back from meta.next_cursor, and filters like department, country, remote, title, company, and ATS are mapped to fields. It does not explicitly explain limit or include_job, but those are relatively self-explanatory and the core polling parameters are well described.

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 identifies what the tool does: it reports events that 'opened, changed, closed or reopened in the index.' It also states that this is a polling tool, which distinguishes it from siblings like search_jobs or get_job, and it names the event types available. The purpose is specific and actionable, not a restatement of the title.

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 strong usage context: 'This is the tool to poll,' explains the since/cursor flow, shows how to filter, and lists concrete use cases like tracking a market or syncing a store. It does not explicitly name sibling tools or state when not to use them, but the polling guidance is clear enough for an agent to select this tool appropriately.

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