ats

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

Annotations already declare readOnlyHint=true, but the description adds substantial behavioral detail: entries are human-confirmed against live portals, share a timestamp due to batch publication, the automated sweep has not yet detected one, rolling re-probing occurs, and a suspected change is human-confirmed before appearing. It also clarifies that an empty list does not indicate monitoring failure. This exceeds what annotations provide and offers rich, non-obvious operational context.

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 concise and well-structured: it opens with purpose, then explains the confirmation process, current state, interpretation of empty results, and return limits—all in a logical order. While a bit lengthy, every sentence adds necessary context (e.g., why timestamps are shared, what happens on rollback), and nothing is redundant.

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 the tool's nuance (confirmation process, timestamp sharing, empty-list meaning, limit), the description covers all crucial aspects. There is no output schema, so the description appropriately includes the return format ('at most 50 rows, newest first'). It also explains the relationship to the dataset, making it complete for an agent to use 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?

The input schema has 100% coverage for the single 'limit' parameter with a description ('Max changes to return (default 50, the cap)'), so the schema already fully documents it. The description adds no additional parameter semantics beyond what the schema states, warranting the baseline score of 3.

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 'which tracked employers changed their applicant tracking system' and positions itself as 'the living-feed counterpart of the dataset.' This distinguishes it from siblings like 'which_ats' (current ATS) and 'ats_stats' (statistics), making the tool's purpose specific and non-redundant.

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 provides clear context on when the tool is useful (see confirmed changes) and explicitly interprets 'an empty list means no confirmed changes yet, not that monitoring is off.' While it doesn't explicitly say 'use X instead of Y,' the 'living-feed counterpart' phrasing implies it complements the static dataset, and the context is sufficient for an agent to decide when to call this tool.

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

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

Annotations already mark the tool as read-only, but the description adds substantial context: dataset source, verification methodology, live computation at call time, and correction of a common misconception (~75% figure). This goes well beyond the annotation-only safety profile.

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?

Three sentences, all high-value: source/methodology, key findings, and usage instruction. No filler, redundancy, or unnecessary detail.

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 a zero-parameter read-only stats tool, the description covers source, verification, key numbers, and live computation. Slight gap: no explicit response structure or field names, but overall it is sufficient 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?

Tool has zero parameters, so baseline is 4. Description appropriately focuses on output semantics rather than parameters; no parameter documentation is needed.

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?

Description clearly identifies the tool as providing canonical ATS market-share numbers from a specific dataset (ResumeAI's State of ATS 2026), with concrete scope (738 large employers, 704 verified). It distinguishes itself from siblings like which_ats (individual employer lookup) and ats_changes (changes over time).

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?

Provides clear context: use this for authoritative market-share figures, and explicitly instructs to quote response values rather than the summary. Does not explicitly name sibling alternatives or state when not to use, so it stops short of a 5.

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

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

Beyond the readOnlyHint annotation, the description discloses concrete return contents (breakdown, fixes, missing keywords), rate limiting (10/day/IP), and paid key behavior. This is significant context that annotations alone don't convey.

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?

Four sentences, each serving a purpose: purpose, return value, optional params, and rate limit/auth. It's a bit detail-heavy with pricing and URLs, but remains well-organized and front-loaded with the core action.

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?

With no output schema, the description fully explains what the tool returns, how each optional parameter alters behavior, and the constraints (rate limit, api_key). It is complete enough for an agent to select and invoke the tool 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 coverage is 100%, but the description adds relational meaning: 'company' triggers employer-specific ATS rules, 'job_description' switches to keyword-overlap scoring, and 'api_key' lifts the daily cap. This goes well beyond the individual parameter descriptions in the schema.

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 'Score a resume 0-100 with ResumeAI's production ATS engine' — a specific verb, resource, and range that clearly states the tool's function. It distinguishes itself from siblings like ats_stats and which_ats by focusing on scoring and returning an actionable breakdown.

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 specifies when to use optional parameters (company, job description, api_key) and notes the rate limit for free usage. Though it doesn't explicitly contrast with sibling tools, the context makes the primary use case clear: to get an ATS score and fixes for a resume.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds important behavior beyond that: the consent-token requirement, token revocation behavior, the guarantee of no enumeration, and the explicit statement that personal data is never exposed without a token. This fully discloses the tool's privacy and safety 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 concise given the complexity of the consent model, front-loads the core purpose, and every sentence adds unique value. It flows logically from what the tool does, to the prerequisite, to the return value, to restrictions and privacy guarantees, with no wasted words.

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?

Even without an output schema, the description specifies the return format (JSON Resume plus ats_context), explains what ats_context contains, covers all relevant edge cases (missing/invalid/revoked token), and describes the tool's limitation (no enumeration). This is fully complete for a single-parameter, consent-gated fetch tool.

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?

The input schema already provides 100% coverage for the single token parameter, including its source URL and length constraints. The description adds behaviorally meaningful semantics: passing the token returns the resume, and invalid/revoked tokens return nothing, which goes beyond the schema's static field definition.

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 uses a specific verb and resource: 'Fetch a job seeker's structured, machine-readable resume as JSON Resume' with a clear distinction from siblings by emphasizing the consent-token-gated nature and the returned ATS context. It clearly differentiates itself from the ATS-focused sibling tools.

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 the critical precondition: the tool can only be used with an owner-minted consent token, and that no token, invalid token, or revoked token returns nothing. It also explicitly rules out browsing/searching/listing, but does not name alternative sibling tools for those use cases; still, the guidance is otherwise very clear.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses the row limit (at most 100 rows per call), the case-insensitive substring matching for ATS vendor and substring matching for industry, and points to the full dataset URL. These are meaningful behavioral details that help the agent predict output size and filter semantics.

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 three sentences, front-loaded with the main purpose, and each sentence adds essential information: the dataset, filter behavior, and output limit/source for full data. No filler or redundancy.

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 is a simple list with optional filters, read-only annotations, and no output schema. The description covers the source dataset, filter behavior, output limit, and full-data alternative. It does not describe the fields of each returned row, but given the known dataset and the link, this is a minor gap.

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?

The schema already covers all three parameters with descriptions. The description adds practical semantics for 'ats' by specifying case-insensitive substring matching with examples, and for 'industry' as substring matching. This goes beyond the schema's basic descriptions. The 'verified_only' parameter is not elaborated in the description, but the schema definition is sufficient.

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 'List employers from the State of ATS 2026 dataset', clearly stating the action (list), resource (employers from a specific dataset), and scope (optionally filtered by ATS and industry). This distinguishes it from siblings like ats_stats or which_ats, which focus on statistics or identification rather than listing companies.

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 provides clear context for use: it can list all companies or filter by ATS and industry. It also states the 100-row limit and advises narrowing filters or fetching the full dataset from the provided URL. However, it does not explicitly name sibling tools as alternatives or exclusions, so it lacks explicit when-not-to-use guidance.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds valuable context: dataset provenance, coverage counts (738 checked, 704 verified), audit dates, and input flexibility (name or slug). This goes beyond the annotations without contradicting them, though it doesn't address not-found behavior.

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?

Two sentences, with the core action front-loaded and dataset details in the second sentence. Every clause earns its place; no redundancy or filler.

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 a single-parameter, read-only lookup with no output schema, the description covers what, scope, dataset, and input format. The return value is implied by the tool name and description, though the exact response shape is not specified. This is adequate for the tool's simplicity.

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 already describes the 'company' parameter with 100% coverage. The description enriches it by giving concrete examples ('Nike', 'jpmorgan-chase') and clarifying that it accepts a name or slug, which helps the agent form valid inputs.

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 'Look up' and resource 'applicant tracking system (ATS)' for a 'specific large employer'. It clearly distinguishes from siblings like ats_changes and list_companies by focusing on identifying the ATS for a named company.

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 provides clear context: use when you have a specific large employer in mind, and it defines the dataset scope (Fortune 500/Global 2000). However, it does not explicitly mention alternatives or when-not-to-use, so it stops short of a 5.

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