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

With no annotations, the description carries the full burden and does meaningful work: it discloses that a board that cannot be read returns a 'error'-typed record rather than failing the call, and it enumerates the normalized output shape. That error-record behavior is exactly the kind of nuance an agent could not guess. It omits any auth, rate-limit, or caching notes, which keeps it from a 5.

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 definition is front-loaded: purpose and input format first, usage triggers second, filters and return shape last. Every sentence carries information and the parenthetical example clarifies the slug syntax efficiently. It is slightly dense with the ATS enumeration and the return-field list, which keeps it just under maximal conciseness.

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 8-parameter read tool with no output schema and no annotations, the description covers the important ground: input format, use cases, available filters, normalized return fields, and degraded-mode behavior. The one gap is that the default per-company cap and the pagination/truncation behavior are not addressed in prose; otherwise an agent has what it needs to call this 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 description coverage is 100%, so every parameter already has a documented meaning in the schema and the baseline is 3. The description lists the filter names (keyword, location, remote, department, postedSince, withSalary) but adds no syntax or semantics beyond what the schema fields already state; it does not even mention maxJobsPerCompany.

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 opens with a specific verb and resource ('List open jobs') and immediately bounds the scope to five named ATS providers. It also states the accepted input forms ('careers URL or "ats:slug"') with a concrete example, so an agent knows exactly what the tool operates on. Siblings (get_transcript, read_x_post, etc.) are unrelated, so no differentiation is needed.

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 gives explicit trigger conditions: 'Use when the user asks who is hiring, what roles a company has open, or to find remote or engineering roles at a named company.' That is clear context for invoking the tool. It stops short of a 5 because it names no exclusions or alternative tools for cases like a non-supported ATS, leaving the agent to infer the boundary.

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