ats_ashby_form

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces these by stating 'This reads the form; it never writes to it, and nothing here submits anything.' It adds detail on error handling (in-band status+detail with specific codes) and clarifies that post-submit surveys are counted but not expanded. This goes well beyond the annotations and gives the agent a clear behavioral model.

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 serves a purpose: purpose, usage context, parameter sourcing, error semantics, and scope boundaries. It front-loads the core purpose and decision-driving summary line. No filler 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?

The tool has an output schema (not shown here) but the description already describes what it returns (sections, fields, required flags, paths, choices) and how to interpret the summary. It covers error handling, the meaning of NOT_FOUND, and what it does not do (expand post-submit surveys). For a read-only inspection tool with clear inputs and outputs, nothing essential is missing.

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 0%, so the description must fully explain parameters. It clearly explains slug and job_posting_id, including where to find them in ats_fetch_board results. It does not explicitly explain response_format, though the enum (markdown/json) and default are self-evident from the schema. Since two of three parameters are thoroughly documented and the third is trivial, this is a strong score just short of 5.

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 states a specific verb ('Read'), a precise resource (one Ashby posting's application form), and exactly what it reports (every question verbatim, with section, field, type, required flag, path, and select choices). It clearly distinguishes from siblings like ats_fetch_board (which lists postings) and check_posting (which likely checks status) by focusing on the form content. No ambiguity.

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 explicitly states when to use it: 'Use this before building an application packet.' It explains that the summary line classifies the form and determines whether drafting time is needed, and it clarifies that this tool only reads and never submits. It also gives interpretive guidance for NOT_FOUND as a meaningful answer rather than an error, which helps the agent decide how to proceed.

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