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

With no annotations, the description carries the burden and does disclose the non-obvious default: attachments land on application_id if given, otherwise on the candidate's most recently active application, with the response's application_id indicating which. That is genuine behavioral value. It stops short of stating auth/permission requirements, failure modes, or the visibility default, so it isn't fully transparent.

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?

Front-loaded with the verb and the write-operation warning, and each following sentence carries routing or defaulting information. The hard line breaks make it slightly choppier than necessary, but there is no 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?

An output schema exists, so return values needn't be re-explained, and the description covers the mutation nature, the application-resolution default, and the sibling alternative. What remains thin is permission/auth context for a write operation with no annotations, but for a simple attach call the essentials are present.

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 all seven parameters are already documented, including the url-vs-content exclusivity, type values, and application_id default. The description largely reiterates the application_id fallback and points at where to find candidate_id rather than adding new syntax or format detail. Baseline 3 is appropriate.

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?

States a specific verb and resource ('Attach a file ... to a candidate') and immediately labels it a write operation. It distinguishes itself from the sibling add_attachment_to_application by naming that alternative explicitly, so an agent can pick the right tool without opening a schema.

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?

Gives concrete when/when-not routing: use search_candidates_by_name to obtain candidate_id, and inspect get_candidate's applications array or switch to add_attachment_to_application when you need to pick the application. It also explains the omission case for application_id. Nothing is left to inference.

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?

With no annotations, the description carries the full burden; it labels the operation a 'Write operation' and notes the type is inferred from the filename extension, which is useful. However it says nothing about permission/auth requirements, overwrite or duplicate-filename behavior, or whether the write is reversible. Adequate but thin for a mutation tool with zero annotation coverage.

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?

Purpose is front-loaded in the first sentence, followed by the id-discovery workflow and the sibling note. Every sentence earns its place, though the arrow-chain workflow is slightly verbose.

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?

An output schema exists, so return values need no explanation, and the schema fully documents parameters. The description supplies the two things structured fields can't: the id-discovery workflow and sibling disambiguation. Only the behavioral/permission context is missing for a write 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?

Schema description coverage is 100%, so all six parameters are already documented (including the url/content either-or and visibility values). The description adds only the filename-extension-to-type inference note, which is marginally useful but slightly at odds with 'type' being a required enum-like parameter. Baseline 3 is correct.

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?

States a specific verb and resource ('Attach a file to a specific application') and explicitly distinguishes itself from the sibling add_attachment ('does the same when you only know the candidate'). An agent can tell the two apart without opening either schema.

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 a concrete workflow for obtaining the required application_id (search_candidates_by_name → get_candidate → match to job) and names the alternative tool plus the condition that selects it (candidate-only knowledge). Both when-to-use and the alternative are explicit.

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?

With no annotations, the description carries the full behavioral burden. It discloses that this is a 'Write operation' and that IDs are custom field option IDs in Harvest v3, which is useful. But it omits required-permission/auth needs, duplicate-handling, reversibility, and which fields are mandatory beyond the schema's single required param.

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?

Compact and front-loaded: the core action and 'Write operation' signal come first, followed by the ID lookup guidance. No wasted sentences, though the sentence fragments are slightly telegraphic.

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?

An output schema exists, so return values need no explanation, and the schema fully documents parameters. The description supplies the lookup workflow needed to populate IDs. It is nearly complete for a write tool, with the only gap being mutation behavior (duplicates, effects on existing entries).

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 the schema already documents every parameter, including date formats and the lookup source for each ID. The description's added value is mostly the Harvest v3 option-ID note, which is marginal. Baseline 3 applies.

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?

States a specific verb and resource: 'Add an education entry to a candidate.' An agent immediately knows the action. However, it does not differentiate from the sibling remove_education or explain the relationship to other candidate sub-resource tools, so it falls short of a 5.

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 concrete prerequisite chains for the ID parameters (search_candidates_by_name for candidate_id, list_schools/list_degrees/list_disciplines for the option IDs). This is clear usage context, though it offers no when-not-to-use guidance or alternatives among candidate-editing tools.

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?

With no annotations, the description carries the full burden and does disclose the key traits: it is a 'Write operation' and it records rather than sends an email. It omits permissions/authorization requirements and the side effects of the visibility setting, so it is not fully complete but adds meaningful behavioral 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?

Purpose and write-nature are front-loaded in the first line, with supporting detail after. Slight redundancy between 'Log an email,' 'Records an email exchange,' and 'This logs the email,' but every line still carries a distinct point (purpose, fields, disambiguation, prerequisite).

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?

An output schema exists, so return values need no explanation, and the description covers the write semantics, the log-not-send distinction, and candidate_id acquisition. For a mutation tool with zero annotation coverage it is close to complete, lacking only permission/authorization context.

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%, so the baseline is 3, and the description modestly exceeds it by listing the recorded fields (to, from, cc, subject, body) and explaining how to source the required candidate_id. It adds no format or validation detail beyond what the schema already documents.

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?

States a specific verb (Log) and resource (an email on a candidate's activity feed) and immediately disambiguates the action with 'This logs the email — it does not send one,' which separates it from a real email-sending operation. An agent can identify the tool's intent without opening the schema.

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?

Gives clear context (log vs. send) and a concrete prerequisite by routing the agent to search_candidates_by_name for the candidate_id. It does not explicitly contrast with the generic sibling add_note_to_candidate, so it stops short of full when-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?

With no annotations, the description carries the full behavioral burden. It discloses two useful traits: this is a write operation and the added address remains unverified until the user confirms. However, it omits permission requirements, uniqueness/conflict behavior, and reversibility, leaving meaningful gaps for a mutation tool.

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 short sentences, front-loaded with the operation and its write nature, followed by practical retrieval guidance and a behavioral note. 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?

An output schema exists, so return values need not be explained. For a low-complexity write tool with no annotations, the description covers purpose, mutation nature, parameter sourcing, and verification behavior. Minor gaps remain around permissions and duplicate-email handling.

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 the schema already defines all three parameters. The description adds value by explaining how to source user_id and by clarifying the verification lifecycle that send_verification influences, going beyond the schema's terse labels.

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 and resource: 'Add a secondary email address to a Greenhouse user.' This distinguishes it from sibling tools like add_email_note_to_candidate, which targets a different resource. An agent can identify the operation without opening the schema.

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 explicitly tells the agent how to obtain the required user_id ('To find user_id: list_users → match by name or email'), which is actionable prerequisite guidance. It does not state when to use this tool versus alternatives like update_user, so it falls short of full when/when-not coverage.

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?

With no annotations, the description carries the full burden and does disclose the key trait: 'Write operation.' It also reveals that Greenhouse requires company_name, title and start_date even though the schema marks them optional/null-defaulted — real behavioral information not visible in the schema. It omits what happens on duplicate entries or what the response contains, but the output schema covers returns.

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?

Very short and front-loaded: purpose first, then the mutation nature, then the constraint and the lookup hint. Every sentence earns its place, though the line-break formatting is slightly choppy.

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 write tool with no annotations, the description covers the mutation semantics, the effective required fields, and how to obtain the required candidate_id, and an output schema exists to explain returns. Remaining gaps (duplicate handling, permissions) are minor.

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%, so the baseline is 3, but the description adds meaning beyond the schema by stating that company_name, title and start_date are effectively required by Greenhouse despite the schema's null defaults and single-required-parameter list. That corrects a potentially misleading schema signal.

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?

States a specific verb and resource ('Add an employment entry to a candidate'), which cleanly separates it from sibling mutations like add_education and remove_employment. It does not explicitly name or contrast with those siblings, so it stops short of a 5.

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 one concrete routing instruction for a prerequisite ('To find candidate_id: search_candidates_by_name'), which is genuinely useful. However, it gives no guidance on when to use this tool versus related tools (add_education, remove_employment) or any preconditions beyond the ID lookup.

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?

With no annotations, the description carries the full behavioral burden: it discloses that this is a write operation requiring admin privileges, which is genuinely useful. It stops short of saying what happens on duplicate grants, whether it affects existing jobs, or how the grant is reversed, leaving meaningful gaps for a mutation tool with zero annotation coverage.

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?

Front-loads the core operation and the admin-only constraint before any parameter detail, and every sentence is functional. The telegraphic one-line-per-parameter style is efficient but slightly abrupt, keeping it just below top marks.

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 a full output schema (return values need not be described), the description covers purpose, authorization level, scoping, and helper tools for every parameter. The only real omission is an explicit contrast with add_job_permission and the removal path for the grant.

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 the baseline is 3. The description's guidance for user_id/user_role_id/office_id/department_id largely restates what the schema already declares ('get from list_users', etc.); the only marginal addition is framing office_id and department_id as scoping levers.

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?

States a specific verb ('Auto-grant'), resource ('a role'), and scope ('on all future jobs'), which cleanly separates it from the sibling add_job_permission (current jobs) and remove_future_job_permission. An agent can identify the operation without opening any schema.

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 a concrete user-utterance example that maps intent to this tool, plus explicit prerequisite lookups (list_users, list_user_roles, list_offices, list_departments) for building the call. It does not, however, state when NOT to use it versus add_job_permission, so the boundary is inferable rather than explicit.

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?

No annotations are provided, so the description carries the full behavioral burden, and it does useful work: it declares 'Write operation,' clarifies the additive (non-destructive) semantics, and discloses partial-failure behavior via per-member 'errors.' It omits permission/auth requirements, which is a minor gap for a mutation tool.

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?

Front-loaded with the core action and its key distinction, then the ID-lookup workflow and return shape. Every sentence earns its place with no 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?

Output schema exists, so return values need not be spelled out (though it helpfully summarizes 'added' and 'errors'). For a mutation tool with no annotations, it covers the essential write semantics and ID-sourcing prerequisites; only auth/permission context 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 description coverage is 100%, so all five parameters (job_id, sourcers, recruiters, coordinators, hiring_managers) are already documented, including the candidate_responsibility enum values. The description adds how to obtain IDs, but that is usage guidance rather than added meaning about the parameters themselves, so the baseline 3 applies.

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?

States a specific verb and resource ('Add members to a hiring team') and immediately differentiates from the sibling replace_hiring_team with 'without replacing existing ones.' An agent can distinguish this from replace_hiring_team and remove_hiring_team_member without opening any schema.

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?

Gives concrete guidance for sourcing required IDs ('list_jobs → match by name', 'list_users → match by name') and implies when this is the right tool via the additive-not-replacing framing. It stops short of explicitly naming replace_hiring_team as the alternative to use when replacement is intended, so it is strong but not fully explicit.

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?

With no annotations provided, the description carries the full burden and does disclose the two most important traits: it is a write/mutation and it requires admin rights. It stops short of describing idempotency, behavior on existing grants, or what a failed grant returns.

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?

Front-loads the core action, then demotes the lookup mechanics to a secondary block. The 'give Sarah recruiter access' example earns its place by translating a natural user request into the tool call, though the id-resolution notes partially duplicate the schema.

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 3-parameter write tool with an output schema present, the description covers purpose, precondition, and argument sourcing, which is enough to invoke correctly. It need not explain return values, and the only real gap is sibling differentiation.

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 each parameter is already documented in the schema (get from list_users / list_jobs / list_user_roles). The description mostly repeats that guidance; its only added value is the role_type 'job_admin' qualifier, so the baseline 3 is appropriate.

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?

States a specific verb (grant) and resource (a role on a job), so the operation is unambiguous. However, it does not distinguish itself from the near-identical sibling add_future_job_permission, so an agent can't tell the two apart from the description alone.

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?

Gives a concrete routing workflow: use list_users to resolve user_id, list_jobs for job_id, and list_user_roles for user_role_id. It states the admin-only precondition but never says when to prefer this over add_future_job_permission or how it relates to remove_job_permission.

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?

With no annotations, the description carries the full burden and does well: it discloses that this is a write operation and that it is admin-only, plus a validation constraint from the job board. It does not describe duplicate handling, failure modes, or reversibility, which keeps it below 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?

Four short lines, front-loaded with the action and the auth constraint, and no filler. The line breaks fragment related ideas slightly but nothing is wasted.

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?

An output schema exists so return values need no explanation, and the description covers purpose, mutation class, auth level, a precondition, and an ID-lookup path. It is close to complete; only edge-case behavior on duplicates or invalid location types is absent.

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 the baseline is 3. The description only touches job_post_id, and its suggestion ('list_job_posts_for_job') actually diverges from the schema's own guidance ('get from list_job_posts'), which muddies rather than clarifies the source tool.

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 gives a specific verb and resource ('Add a location to a job post') and scopes it to v3 job posts that can have several locations. It is clearly distinct from remove_job_post_location and update_job_post, though it never names those siblings explicitly.

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 supplies a concrete precondition ('The post's job board must allow the location type') and routes the agent to list_job_posts_for_job for obtaining job_post_id. There is no explicit when-not-to-use statement or comparison against the removal sibling, so it falls 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?

No annotations are provided, so the description carries the full burden. It discloses that this is a write operation and that the note is authored by the configured Greenhouse user, but says nothing about required permissions, editability/deletion, 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?

Purpose is front-loaded in the first sentence, and each subsequent line (write-op flag, authorship, ID acquisition) earns its place. Slightly fragmented across lines, but no 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?

With an output schema present, return values need not be explained, and the description covers purpose, authorship, and ID lookup for a write tool. The main gap is the absence of permission/authorization context, which matters for a mutation with no annotations.

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%, so the schema already documents all four parameters and the baseline is 3. The description adds real value by telling the agent how to source candidate_id via search_candidates_by_name, which is beyond what the schema states.

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?

States a specific verb and resource ('Add a text note to a candidate's Notes tab / activity feed'), which is clear. It distinguishes itself from the text-note family by specifying 'text note' and naming the destination surface, though it never explicitly rules out the close sibling add_email_note_to_candidate.

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 concrete natural-language triggers ('add a note to Sarah's profile', 'log that I spoke with John') and points to search_candidates_by_name for obtaining candidate_id, which gives clear context. It lacks any explicit when-not or alternative-tool exclusion 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?

No annotations are provided, so the description carries the full burden. It does disclose the key trait 'Write operation' and clarifies the object is a prospect not yet in an active pipeline. However it omits permission requirements, behavior on duplicate prospects, and any error/validation semantics that a mutation tool should surface.

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?

Content is front-loaded with the operation and mutation flag, and each subsequent sentence adds routing value. Slightly verbose with a redundant restatement of the ID-sourcing already in the schema, but no dead weight.

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?

An output schema exists, so return values need not be explained. Combined with 100% schema coverage, the description supplies the routing, mutation flag, and ID resolution an agent needs. Missing only edge-case behavior (duplicates, permissions) for full completeness.

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 each of the 10 parameters is already documented in the schema (including the list_prospect_pools / list_users sourcing hints). The description's 'For pool/stage IDs: list_prospect_pools → match by name' largely restates that, adding little new meaning. Baseline 3 applies.

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?

States a specific verb and resource ('Create a sourced prospect in a prospect pool') and explicitly distinguishes itself from create_candidate (job_id → pipeline) and convert_prospect. An agent can select this correctly without opening the schema.

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?

Gives explicit when-to-use ('Users say add this person as a prospect for the pool'), when-not (unlike create_candidate with job_id), the ID-resolution path (list_prospect_pools → match by name), and the follow-up tool (convert_prospect). Routing is fully specified.

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?

With no annotations provided, the description carries the full burden. It explicitly labels the operation as 'Write operation', which is useful, and implies tags must already exist (via 'list_tags → match by name'). However, it does not disclose idempotency, behavior on duplicate tags, permissions required, or error conditions, leaving notable gaps in behavioral transparency.

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: a one-sentence purpose, followed by terse usage examples, ID resolution tips, and a single alternative tool mention. Every sentence earns its place with no 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?

For a simple two-parameter write operation with an output schema present, the description covers purpose, usage, ID resolution, and alternatives. It does not explain edge cases like duplicate tags or required permissions, but these are not essential for basic invocation. The explicit 'Write operation' flag partially compensates for missing annotations.

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% with descriptions for both candidate_id and tag_id. The description adds value beyond the schema by recommending how to find each ID (search_candidates_by_name, list_tags → match by name) and providing real-world usage phrasing that helps the agent map user intent to parameters.

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 'Apply a tag to a candidate' with a specific verb and resource. It also distinguishes itself from the sibling tool bulk_tag by explicitly directing bulk tagging elsewhere, and the name itself differentiates from add_note_to_candidate.

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 explicit when-to-use guidance with natural language examples ('tag Sarah as referred'), how to resolve candidate_id and tag_id via search_candidates_by_name and list_tags, and an explicit exclusion for bulk tagging ('use bulk_tag instead'). This fully covers usage context and alternatives.

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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: it flags 'Write operation', warns that Greenhouse rejects stale moves unless from_stage_id matches the current job_interview_stage_id, and notes that omitting from_stage_id triggers an automatic lookup. It stops short of covering permission/auth requirements or failure modes beyond the staleness check, so it is strong but not exhaustive.

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?

Front-loads the core action in the first sentence, then layers the ID-resolution workflow, parameter constraints, and alternatives. Every sentence earns its place; the quoted user utterances map directly to routing decisions rather than being 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 3-param write tool with no annotations but with an output schema (so return values need no explanation) and full schema coverage, the description supplies the workflow, the key failure constraint, and the sibling alternatives. It omits permission/auth context and non-staleness error behavior, leaving a small but real 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: from_stage_id must equal the application's current job_interview_stage_id or the write is rejected, and omitting it is auto-resolved; omitting to_stage_id advances to the natural next stage. That constraint-level detail exceeds what the property descriptions state.

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?

States a specific verb+resource+scope: 'Move a candidate forward one stage in their job pipeline.' It explicitly names and distinguishes the two nearest siblings, move_application_same_job (skipping stages) and bulk_advance (bulk), so an agent can route correctly without opening any schema.

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 explicit when-to-use via user utterance examples ('advance Sarah to the next stage'), states the preconditions for the key input (how to obtain application_id via search_candidates_by_name → get_candidate → match to job), and names alternatives with the condition that selects them (skip stages, bulk advancing). Nothing is left to inference.

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?

With no annotations, the description carries the full burden and does well: it declares a write operation, irreversibility, asynchronous completion for large scopes, and the requirement for an explicit field list. It stops short of stating permission/auth requirements 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?

Purpose is front-loaded in the first sentence, followed by the critical constraints (irreversible, async, explicit fields) in order of importance. Every sentence carries operational weight with no 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 two-parameter destructive mutation with an output schema present, the description covers everything an agent needs to act correctly: what gets scrubbed, what is preserved, reversibility, async behavior, and how to source the ID.

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%, so both parameters are already documented and the field list is enumerated in the schema. The description still adds value by warning that Greenhouse requires an explicit field list, advising confirmation with the user, and showing the search_candidates_by_name → get_candidate path for candidate_id.

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+resource ('Anonymize a candidate's personal data') with an explicit compliance motivation (GDPR/privacy). It distinguishes itself from the sibling delete_candidate by stating it preserves the record and hiring activity for reporting.

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 clear context (GDPR/privacy compliance, the need to confirm scope with the user) and a navigation path to obtain candidate_id. It does not explicitly name delete_candidate as the alternative for a hard removal, leaving that contrast to inference.

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?

With no annotations, the description carries the full burden, and it does disclose two meaningful traits: the operation is 'Read-only' and it selects each candidate's most recent resume across all applications. It does not cover rate limits, permissions, or failure behavior for large batches, so it stops short of full disclosure.

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 short sentences, front-loaded with the verb and read-only note, then usage, then behavior. The final sentence justifies why the tool is worth calling rather than padding.

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?

An output schema exists, so return values need no explanation, and the description covers purpose, preconditions, and resume-selection semantics. It omits auth/permission requirements and any limits on batch size behavior, a minor gap for a batch download tool with no annotations.

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%, so the baseline is 3. The description adds real meaning beyond the schema by stating where candidate_ids should originate (search_pipeline_candidates or scan_all_candidates), which guides correct invocation. It says nothing extra about max_candidates, which the schema already documents.

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?

States a specific verb pair (download and extract) and resource (resume text) scoped to 'a list of candidates,' which distinguishes it from the singular read_candidate_resume sibling. An agent can tell what it produces without opening the schema.

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?

Explicitly says to use it 'after narrowing candidates with other sourcing tools' and names the two siblings that produce valid candidate_ids (search_pipeline_candidates, scan_all_candidates). This is a clear precondition plus a routing rule, not vague 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?

With no annotations, the description carries the full behavioral burden and does so: it declares this is a write operation, that it is rate-limited, that processing is sequential with rate-limit delays, and enumerates the skip rules (rejected/hired/prospect apps, and apps not currently in from_stage_id).

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?

Front-loads the operation and its write/rate-limit nature, then adds usage, mechanics, and edge cases in compact sentences with no filler. Every sentence conveys a distinct fact an agent needs.

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?

Both parameters are documented, an output schema exists so return values need no explanation, and the description covers the mutation semantics, rate limiting, and skip behavior for a bulk write tool with no annotations.

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%, so the baseline is 3, but the description goes further by explaining the skip consequence of from_stage_id ('others are skipped'), how to derive it (list_job_stages_for_job, match by name), and where to obtain application_ids, which the schema does not say.

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?

States a specific verb (advance), resource (applications), and scope (multiple / bulk) in the first clause, which cleanly separates it from the single-application sibling advance_application. It also names the exact state transition: each app moves to the next stage on its job's interview plan.

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?

Gives concrete routing for inputs ('Get application_ids from pipeline_summary or list_applications'), a real user phrasing that triggers it, and a clear condition for when to use from_stage_id. It never explicitly says to use advance_application for a single app, but the bulk framing and the source-tool pointers cover the practical decision.

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?

With no annotations, the description carries the full burden and does disclose meaningful traits: it is a write operation, it requires admin privileges, and it is asynchronous with a deferred result. It omits batch-size limits, partial-failure semantics, and idempotency, which matter for a bulk mutation, so it falls short of 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?

Three short sentences, front-loaded with the core operation, then permissions, then return/follow-up and the alternative. Every sentence earns its place with no 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 an async bulk mutation, the description covers the operation, the auth requirement, the return artifact, and the polling tool, and an output schema exists so return structure needn't be spelled out. Missing only edge-case behavior such as partial failures or limits, which keeps it from a 5.

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 both openings and callback_url are already documented in the schema, including the nested field breakdown and the callback's purpose. The description adds no syntax or format detail beyond the schema, which is the expected baseline when the schema does the work.

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?

States a specific verb and resource with scope ('Create many openings in one asynchronous request'), and explicitly contrasts itself with the single-item sibling create_job_opening. An agent can distinguish it from bulk_update_job_openings and create_job_opening without opening any schema.

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?

Explicitly routes the agent in both directions: 'For one opening use create_job_opening' for the alternative, and 'check progress with get_bulk_request_status' for the follow-up. The when-to-use condition (multiple openings, async) is stated rather than implied.

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?

With no annotations, the description carries the full burden and does well: it flags the operation as destructive and irreversible, states it is asynchronous, and names the returned bulk_action_uuid plus the follow-up tool. It omits permission/auth requirements and rate limits, which would round it out.

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 compact sentences, zero waste, with the destructive/irreversible warning front-loaded ahead of the follow-up guidance.

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 destructive async bulk tool with an output schema present, the description supplies the essential context: irreversibility, async semantics, and the progress-check sibling. Nothing needed to call it correctly 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 100%, so both parameters (opening_ids, callback_url) are already documented in the schema. The description adds no syntax or format detail beyond what is structured, so the baseline 3 applies.

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?

States a specific verb (Delete) plus resource (openings) plus scope (many, in one asynchronous request). The bulk/async framing cleanly separates it from the singular delete_job_opening and from bulk_create/update_job_openings siblings.

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?

Implies bulk use and explicitly routes the agent to get_bulk_request_status for progress. It doesn't name delete_job_opening as the alternative for single deletions, so the when-not case is left to inference.

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?

With no annotations, the description carries the burden well: it declares this is a write operation, that it is rate-limited, and that it processes sequentially with rate-limit delays. It also distinguishes internal notes from candidate-facing email. It stops short of stating irreversibility or required permissions.

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?

Purpose is front-loaded, followed by the write/rate-limit caveat and a concrete user-utterance example that aids semantic matching. Every sentence either instructs or routes; nothing is padding.

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 6-parameter bulk mutation with an output schema already present, the description covers prerequisites, the multi-step ID resolution, email behavior, and rate-limit processing. Nothing an agent needs to call it correctly 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 100%, so the baseline is 3, but the description adds genuine resolution guidance — rejection_reason_id is required and must be looked up via list_rejection_reasons and matched by name, and email_template_id via list_email_templates. This goes beyond restating 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?

States a specific verb and resource ("Reject multiple applications in one call") and its plural scope distinguishes it from the singular reject_application sibling. An agent can identify the operation immediately.

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?

Gives a concrete routing workflow: use stale_applications to find targets, then pass application_ids here, and it shows a real-world trigger ("reject everyone inactive for 30 days"). It never explicitly contrasts against reject_application for a single ID, leaving that boundary to inference.

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?

With no annotations, the description carries the full burden and does well: it flags that this is a write operation, that it is rate-limited, that existing tags cause candidates to be skipped (idempotent-ish behavior), and that processing is sequential with delays. It omits permission/auth requirements and any failure semantics for invalid IDs.

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?

Front-loads the core action and the write/rate-limit caveat, then adds only the details an agent needs. Short, well-ordered sentences with no 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?

Output schema exists, so return values need not be explained, and both params plus the mutation/rate-limit behavior are covered. Minor gaps remain around permissions and error handling for invalid candidate IDs, but the definition is sufficient to call 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%, so both parameters are already documented in the schema (including on-the-fly tag creation and where to source IDs). The description largely restates this, adding only 'pipeline tools' as an extra ID source, so the baseline 3 applies.

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?

States a specific verb (tag) plus resource (candidates) and scope (multiple in one call), which implicitly distinguishes it from the single-target sibling add_tag_to_candidate. It does not explicitly name that alternative, so it falls short of a 5.

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?

Gives a source hint ('pass candidate_ids from search or pipeline tools') and a representative user utterance, which helps routing. However, it never explicitly states when to use this bulk tool versus add_tag_to_candidate, nor any exclusions or prerequisites, so usage is only implied.

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?

With no annotations, the description carries the burden and does well: it declares this a write operation, flags the asynchronous execution model, and names the returned bulk_action_uuid with a pointer to get_bulk_request_status for progress. It omits permission requirements and reversibility, keeping it below 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?

Three short sentences, front-loaded with the core action, then usage, then return/polling guidance. Every sentence earns its place with no 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?

For a no-annotation mutation tool with an output schema, the description covers the essentials: what it does, the async flow, and how to check progress. It leaves permission requirements and the scope of updatable fields to the schema, which is acceptable given the rich input schema.

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 the schema already documents both the openings object and callback_url. The description only adds a workflow hint on where to get ids; it adds no syntax or field-level meaning beyond the schema, matching the baseline 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?

States a specific verb and resource ('Update or close many openings') plus the async batch nature, which naturally separates it from bulk_create_job_openings and bulk_delete_job_openings. It does not explicitly name those siblings, so it falls just short of a 5.

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?

Gives a concrete use case ('close all of a job's openings at once') and a workflow hint ('list_job_openings → ids') for sourcing input. However it names no alternatives or when-not conditions, so it stops at clear context rather than explicit routing.

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?

With no annotations, the description carries the safety burden and does so by declaring 'Read-only' — the single most important behavioral fact. It also previews what comes back (stale applications sorted by urgency, interviews awaiting feedback, interviewers with missing scorecards). It stops short of permissions, pagination, or result limits, which an unannotated tool arguably should mention.

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?

Front-loaded with the one-line purpose, then usage phrasings, then parameter guidance, then return shape — a sensible ordering with no filler. The only mild redundancy is repeating the 'list_jobs → match by name' mapping already present in the schema.

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?

An output schema exists, so the description needn't explain return values, yet it does anyway, and it covers purpose, scoping, and both parameters. The remaining gap is the unaddressed relationship to the very similar 'stale_applications' sibling, which could cause an agent to pick the wrong 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: omitting job_id returns 'all active applications' (the schema only shows a null default), and it explains how to obtain a job_id via list_jobs. stale_days is left to the schema, which is acceptable since the schema documents it.

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 gives a specific verb and resource — 'find candidates that need attention' — and enumerates the concrete cases it covers (stale apps, missing scorecards, interviews awaiting feedback), which is far more than a restatement of the name. It does not, however, distinguish itself from the close sibling 'stale_applications' or 'pipeline_summary', leaving the agent to infer the boundary.

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?

Usage context is made explicit through the user-intent phrasings ('what needs my attention?', 'who's been sitting too long?'), which tells an agent when this tool matches a request. It also explains the two scoping modes (job_id vs omit). What's missing is any when-not-to-use guidance or an explicit pointer to the overlapping sibling tools.

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?

With no annotations, the description carries the full burden and does well: it declares this is a write operation, that it is admin-only, and that it destroys Site Admin status plus all job-level permissions. It stops short of stating reversibility or whether any residual access remains, which is a minor gap for a destructive permission change.

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?

Front-loaded with the effect and safety constraint, then alternatives, then parameter discovery. Well organized across a few short lines, though slightly more verbose than strictly necessary.

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?

Covers the mutation's destructive scope, authorization requirement, the impossibility of the inverse operation, and the alternative tool, while an output schema handles return values. An agent has everything needed to decide and call 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% so the baseline is 3, but the description adds value the schema does not: how to locate user_id (list_users, match by name or email). The permission_level constraint is already fully documented in the schema, so this is additive rather than redundant.

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?

States a specific verb and resource (demote a user to Basic) and immediately names the exact effect: removal of Site Admin status and every job-level permission. It is clearly distinguishable from siblings like add_job_permission or update_user, which the description explicitly contrasts.

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?

Explicit when-to-use (demoting a user, admin only), explicit when-not (promotion is not possible via the API), and names the alternative (grant job roles with add_job_permission). It even supplies the discovery path for the required user_id via list_users.

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?

With no annotations, the description carries the full burden. It does disclose 'Write operation' and that the prospect becomes an active candidate on a target job, but says nothing about permissions required, reversibility, whether the prospect record is removed, or side effects such as notifications. Useful but incomplete for an unannotated mutation.

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?

Purpose and write-nature are front-loaded in the first two short sentences, and the remaining sentences give input-sourcing workflow. The 'Users say...' sentence is slightly filler but does map natural language intent to the tool, so it earns most of its place.

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?

An output schema exists so return values need not be explained, but for an unannotated write tool the description omits key operational context: side effects of conversion, error cases, and prerequisite state (e.g., prospect must exist and not already be converted). Adequate rather than complete.

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%, so the baseline is 3, and the schema already says job_id comes 'from list_jobs'. The description adds real meaning by specifying that application_id is the prospect's application (identified via get_candidate where prospect is true), but it leaves initial_stage_id entirely to 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?

States a specific verb and resource ('Convert a sourced prospect into an active candidate on a job'), which is distinguishable from siblings like create_candidate, create_application, and advance_application. An agent can tell what this does and that it is a state transition, not a creation.

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 practical routing context — the user phrasing to expect ('move this prospect into the Backend pipeline'), plus where the two required IDs come from (get_candidate → applications array with prospect=true; list_jobs → match by name). It does not state when NOT to use this versus the many application/candidate siblings, so it stops short of full when/when-not 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?

With no annotations, the description carries the full burden and does well: it declares this is a write, states attachments are uploaded after creation and returned under attachment_results, and notes initial stage defaults to the first stage. It stops short of auth/permission requirements or idempotency behavior, so it is strong but not exhaustive.

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?

Front-loads the core action and write nature in the first two lines, then layers resolution steps, the existence precondition, attachment behavior, and sibling alternatives. Every sentence earns its place; the line breaks aid scanning without padding.

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 write tool with an output schema and no annotations, the description covers the workflow, preconditions, side effects (attachments), and routing to alternatives. It could say more about permission requirements or what the returned application record contains, but nothing essential to correct invocation 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 100%, so the baseline is 3, but the description adds real meaning: it explains how to resolve candidate_id and job_id (which lookup tools to use) and clarifies that attachments are applied post-creation with results under attachment_results. That is workflow context the schema does not supply.

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?

States a specific verb+resource ("Apply an existing candidate to a job") and immediately labels it a write operation. It distinguishes itself from near-neighbors by naming create_candidate, add_prospect, and post_candidate as different flows, so an agent can route without opening schemas.

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?

Gives explicit preconditions and resolution steps: candidate must already exist, resolve candidate via search_candidates_by_name and job via list_jobs. It also names the alternatives and the condition that selects each (create_candidate for one-step creation, add_prospect for sourced prospects, post_candidate for partner submissions).

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?

No annotations are provided, so the description carries the full burden, and it does disclose the mutation nature ('Write operation'), the response shape when job_id is passed, and the duplicate-check prerequisite. It stops short of covering permissions/authorization requirements or what happens if a duplicate is detected (hard error vs. soft match).

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?

Front-loads purpose and write-type in the first line, then adds usage flow. The embedded user quote is slightly verbose but earns its place by illustrating the job_id-in-the-same-call pattern; otherwise tight.

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?

An output schema exists, so return-value detail is unnecessary, and the description covers the create/apply fork, the duplicate-check step, and the sibling alternative. For a 15-param create tool with full schema coverage, nothing an agent needs to call it correctly 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 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining the job_id side effect (application created in the same call, response contains both) and the fallback to create_application when it is omitted. Other params are left to the rich schema descriptions.

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?

Opens with a specific verb+resource ('Create a new candidate record') and states scope ('optionally applying them to a job'). It explicitly differentiates from siblings, naming add_prospect and create_application, so an agent can route correctly without opening a schema.

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?

Gives explicit when-to-use rules: check duplicates first with search_candidates_by_name or search_candidates_by_email; pass job_id to fold the application into the same call; without job_id use create_application afterwards. It also names the alternative tool (add_prospect) with the condition (sourced prospects) that selects it.

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?

With no annotations, the description carries the full burden. It usefully discloses that this is a write operation requiring admin privileges, but says nothing about reversibility, whether the field name must be unique, side effects on existing records, or rate/validation constraints.

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 short sentences, front-loaded with the operation and then the critical admin constraint. No filler, though the line-broken entity list adds little and could be tighter.

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?

An output schema exists, so return values need not be explained, and the admin/write framing covers the safety profile. Still, for a 7-parameter creation tool with several sibling field-management tools, the description omits how it relates to those siblings and any uniqueness/validation behavior an agent should anticipate.

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 all seven parameters are documented in the schema itself, including the field_type entity list and value_type vocabulary. The description adds no parameter detail beyond repeating the entity list already present in field_type's schema description.

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?

States a specific verb and resource ('Create a new custom field definition') and lists the entity surfaces the field can attach to, which clarifies scope. It is distinguishable from list_custom_fields and get_custom_field, though it never explicitly names its mutation siblings (update_custom_field, delete_custom_field, create_custom_field_options).

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?

'Write operation — admin only' gives a prerequisite, which is real guidance. However, there is no when-to-use vs. when-not guidance relative to the crowded sibling set of custom-field tools (e.g., create_custom_field_options for dropdown values, update_custom_field for existing definitions).

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?

With no annotations, the description carries the full burden and does well: it declares this is a write operation, that it is admin-only, and that lists up to 50 options are created synchronously and returned while larger lists go through an asynchronous Greenhouse bulk request. It omits reversibility (how options are removed) and error/permission failure behavior, keeping it out of the top band.

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 short lines, front-loaded with the operation and its write/admin constraint, then the ID lookup, then the sync/async threshold. Every sentence earns its place.

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?

An output schema exists, so return values need not be explained, yet the description still covers the key behavioral surprise (sync vs async based on the 50-option threshold) plus the auth requirement and ID acquisition path. Nothing essential is missing for an agent 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 coverage is 100%, so baseline is 3, but the description adds procedural value the schema does not: how to obtain custom_field_id via list_custom_fields and matching by name. It adds nothing for the options array beyond what the schema already documents.

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 gives a specific verb+resource ('Add dropdown options to a custom field'), making the operation unambiguous. It does not explicitly name the sibling tools it is distinguished from (update_custom_field_options, delete_custom_field_options, create_custom_field), so it stops just short of the top band.

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 supplies real routing guidance for the hard part of calling it: 'To find custom_field_id: list_custom_fields → match by name.' It does not state when to use this instead of update_custom_field_options or delete_custom_field_options, nor any exclusions, so it is clear context without explicit alternatives.

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?

With no annotations, the description carries the full behavioral burden. It discloses that this is a write and that admin privileges are required, which is useful. However it says nothing about side effects, uniqueness/dedup behavior on name or external_id, idempotency, or error cases expected of a create operation.

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 short sentences, the core action front-loaded, followed only by the one genuinely needed hint. Nothing is wasted or 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?

An output schema exists, so return values need no explanation, and the permission constraint plus parent_id sourcing hint cover the practical needs of a 3-parameter create tool. The remaining gap is behavioral edge cases (uniqueness, errors) rather than anything blocking correct 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 100%, so baseline is 3. The description adds a pointer for parent_id (optional, obtained from list_departments by name), which is marginally useful, but says nothing about external_id beyond what the schema already provides.

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?

States a specific verb and resource ("Create a new department") so the agent knows exactly what it does, and the verb distinguishes it from siblings get_department, list_departments, and update_department. It doesn't explicitly name those siblings, so it stops short of full differentiation.

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?

Gives concrete context: it is a write operation and admin-only, and it tells the agent how to source the optional parent_id via list_departments. There is no "when not to use" or mention of failure conditions, so it is clear guidance without exclusions.

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?

With no annotations, the description must carry behavioral disclosure, and it does the important part: it states this is a write operation and that it "does not send calendar invites," which prevents a false expectation of outbound notifications. It omits permission requirements, whether duplicate scheduling is possible, and any rate/validation constraints, so it is good but not exhaustive.

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?

Purpose and write-operation warning are front-loaded in the first two sentences, followed by compact ID-resolution recipes. It is terse to the point of being telegraphic, but every sentence carries operational information and nothing is padded.

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 mutation tool this covers the crucial gaps: how to obtain the otherwise opaque IDs and the explicit absence of calendar-invite side effects. An output schema exists, so return-value documentation is not needed, though scheduling-conflict or permission behavior remains unaddressed.

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 the baseline is 3. The description restates the derivation for application_id, interviewer_ids, and interview_id, but the schema already documents those same sources (list_users, list_job_stages_for_job → interviews[].id), so it adds little beyond the structured fields.

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+resource ("Record a scheduled interview for an application") and explicitly labels it a write operation, which cleanly separates it from the read-oriented siblings get_interview, list_interviews, and list_interviews_for_application, and from delete_interview/update_interview.

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 a concrete user-intent trigger ("schedule an interview for Sarah on the Backend role") and step-by-step ID-resolution recipes for application_id, interviewer_ids, and interview_id, so the agent knows the prerequisite lookups. It stops short of explicitly naming alternative tools or stating when NOT to use this (e.g., reschedule vs. create), so it is strong but not fully routing-aware.

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?

With no annotations, the description carries the full burden and does disclose the two most important traits: it is a write operation and it is admin-only. It also fixes the required template_job_id and the post-creation workflow. It does not cover reversibility, error behavior, or how the template's pipeline/approvers propagate, which keeps it short of 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 write/admin declaration is front-loaded, followed by a concrete user example and then a compact ID-discovery workflow. Every sentence contributes a distinct, actionable instruction with no 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?

An output schema exists so return values need no explanation, and the schema documents all 10 parameters. The description supplies behavior (write, admin-only) and the cross-tool ID-discovery workflow, making it largely complete; it could note what the template copy creates (openings, stages) but that 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value beyond the schema by explaining how to derive FK values ('match by name' for department/office) and consolidating the discovery flow. It stops short of covering the remaining scalars (notes, job_name, requisition_id, number_of_openings), which the schema already documents.

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?

States a specific verb and resource ('Create a new job') and adds the distinguishing mechanism 'from a template', which separates it from siblings like create_job_opening and update_job. An agent can identify the operation without opening the schema.

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?

Gives explicit prerequisites and alternatives: template_job_id via list_jobs, department_id via list_departments (match by name), office_ids via list_offices, and the follow-up step update_job_post. It also names the admin-only constraint and provides a user-phrasing example, leaving little to inference.

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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: it flags the operation as a write, states that openings default to open, and explains the non-obvious side effect that status='closed' closes the opening immediately, requiring close_reason_id. It omits permissions/error/rate-limit behavior, so not 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?

Four short segments, front-loaded with the operation and the write classification, then user-phrasing, then a lookup recipe, then default/edge-case behavior. No filler sentences; every clause carries information.

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 5-parameter mutation with an output schema, the description covers what it creates, the default and conditional status behavior, and how to resolve the required job_id. Missing only permission requirements and failure modes, which are minor given the output schema handles return values.

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 the baseline is 3, but the description adds real semantics beyond the schema: the default status value, the conditional dependency between status='closed' and close_reason_id, and how to obtain job_id. It does not clarify the custom_fields or opening_id semantics further.

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 opening sentence names a specific verb+resource ('Add a new headcount to a job') and even maps user phrasing ('add another opening to the Backend role') onto it, so the intent is unambiguous. It does not explicitly distinguish itself from close neighbors like bulk_create_job_openings or create_job, so it falls short of a 5.

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 concrete activation context (the natural-language request it answers) and a prerequisite workflow: 'To find job_id: list_jobs → match by name.' That is more than implied usage, but it names no exclusions or explicit alternative tools for edge cases (e.g., bulk creation).

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?

With no annotations, the description must carry the behavioral burden. It discloses that this is a write operation and admin-restricted, which is valuable, but says nothing about reversibility, failure modes, or side effects beyond creation.

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?

Front-loads the core action and the safety-relevant fact (write, admin only), then adds only the two lines of dependency guidance. No redundant or filler content.

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?

An output schema exists and parameter coverage is full, so return values and field meanings are already documented. Together with the auth and lookup guidance, nothing an agent needs to invoke it correctly is missing. Adjusting to 5 given how little remains uncovered.

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%, so the baseline is 3, but the description adds procedural value beyond the schema by prescribing the lookup workflow (list_offices → find parent by name; list_users → match by name) for the two ID parameters.

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?

States a specific verb and resource ('Create a new office'), clearly distinct from sibling resources like create_department or create_user. It doesn't need to contrast with a near-identical sibling, so the lack of explicit differentiation is minor.

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?

Gives clear operating context ('admin only') and dependency-gathering guidance — use list_offices to resolve parent_id and list_users to match the contact. It stops short of stating when-not-to-use this tool, but the prerequisites are explicit.

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?

With no annotations, the description carries the burden and does well: it declares the write operation, warns that existing approver groups are overwritten, and discloses the resulting pending state requiring request_approvals. It omits permission/auth requirements and error behavior, which keeps it short of 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?

Front-loads the verb, resource, and the critical 'overwrites existing' warning in the first sentence, then layers branch behavior and ID lookups. Every sentence earns its place; 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?

An output schema exists so return values need no explanation, and the description covers the mutation semantics, replacement behavior, pending state, and prerequisite lookups. An agent has everything needed to invoke 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 the baseline is 3, but the description adds real semantic help the schema lacks: how to obtain job_id (list_jobs → match by name) and approver user IDs (list_users → match by name). It doesn't clarify the nested approver_groups structure beyond the schema, so not a 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?

States a specific verb+resource with clear semantics: 'Create or replace an approval flow for a job.' It also implicitly distinguishes itself from siblings by noting the flow is created pending and that request_approvals starts it, versus get_approval_flow/list_approvals_for_job which read state.

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?

Explains the two branches (existing flow of this approval_type → groups replaced; otherwise new flow) and routes the agent to request_approvals for activation plus list_jobs/list_users for ID discovery. It does not explicitly say when to prefer this over replace_approver or get_approval_flow, but the context is 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?

No annotations are provided, so the description carries the full burden. It does declare 'Write operation', which is the key safety signal, and notes the two-step create-then-apply workflow. However it says nothing about permission requirements, what happens on a duplicate name, or idempotency — relevant gaps for a mutation with zero annotation coverage (return format is covered by the output schema, so that omission is acceptable).

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 short sentences, front-loaded with the operation and its write nature, then the follow-up action, then the alternative. Every sentence earns its place and none is redundant with structured fields.

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 one-parameter mutation with an output schema and a well-described parameter, the description is largely complete: it establishes the write nature and routes to the correct follow-up and sibling tools. It falls short only on operational behavior (permissions, duplicate-name handling) that an agent might need under failure conditions.

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?

There is a single parameter and schema description coverage is 100% — the schema already documents both the name field and the organization-wide uniqueness constraint. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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?

States a specific verb and resource ('Create a new candidate tag') and immediately differentiates from the two most confusable siblings: add_tag_to_candidate (applies an existing tag) and bulk_tag (creates tags implicitly). An agent can route correctly without opening any schema.

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?

Gives explicit workflow ordering ('After creating, use add_tag_to_candidate to apply it') and an explicit exclusion ('bulk_tag creates tags on-the-fly, so pre-creation isn't needed for bulk ops'). This is exactly when-to-use / when-not-to-use with named alternatives.

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?

With no annotations, the description carries the full burden; it usefully discloses that this is a write operation and admin-restricted, which the agent needs. However, it omits other behavioral traits such as whether an invitation email is sent by default, error conditions (e.g., duplicate email), or what happens to permissions at creation time.

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, zero waste, front-loaded with the core operation and the admin constraint before the follow-up workflow guidance.

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?

An output schema exists, so return values need not be explained, and the description covers the mutation type, authorization requirement, and next-step workflow. It could do slightly more on side effects like the default invitation email, but is largely complete for a create 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?

Schema description coverage is 100%, so all seven parameters (including office_ids/department_ids sourcing hints and send_email default) are already documented in the schema. The description adds no parameter-level meaning beyond that, so baseline 3 applies.

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?

States a specific verb and resource ('Create a new Greenhouse user account'), clearly distinguishing it from siblings like update_user, disable_user, and create_candidate. An agent can identify the operation without opening the schema.

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?

Adds explicit prerequisites ('admin only') and routes the agent to the two follow-up permission tools with the condition that separates them (specific jobs vs. automatic access to new jobs). It does not state when to prefer this over other creation tools, but the context is 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?

With no annotations, the description carries the full burden and does disclose the crucial trait: permanent, cannot be undone. It stops short of stating cascade scope (whether notes, attachments, interviews, or the candidate record survive) or any permission requirement, which matters for a destructive operation.

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 short, front-loaded statements: capability and risk first, ID discovery second, safer alternative third. No sentence is redundant and nothing is buried.

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?

An output schema exists, so return values need not be described, and the destructive nature plus the safer sibling are covered. The remaining gap is blast radius — what else is removed along with the application — which an agent deciding between delete and reject would want.

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% and there is only one parameter, so baseline is 3. The description adds genuine value beyond the schema's bare 'Greenhouse application ID to delete' by explaining how to derive that ID from a candidate-name search.

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?

States a specific verb and resource ('Permanently delete an application') and immediately qualifies the scope with irreversibility. It is clearly distinguishable from reject_application, which the description explicitly names.

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?

Gives an explicit alternative ('Consider reject_application instead — it preserves history and can be reversed with unreject_application'), which is a when-not-to-use condition, plus a concrete lookup chain (search_candidates_by_name → get_candidate → match the application to the job) for obtaining the required ID.

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?

With no annotations provided, the description carries the full disclosure burden and does well: it states the operation is permanent, cannot be undone, and cascades to all applications. It does not mention permission requirements or any guardrails (e.g. candidates with active offers), which keeps it short of 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?

Three short, front-loaded segments: the destructive action first, then ID acquisition, then the compliant alternative. No filler sentences and nothing buried.

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?

An output schema exists, so return values need no explanation. For a single-parameter destructive tool with no annotations, the description covers the action, its irreversibility, cascade scope, prerequisite lookup, and a safer alternative — everything needed to call it 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% and the schema already documents candidate_id, so the baseline would be 3. The description adds real value by explaining how the ID is acquired via search_candidates_by_name and get_candidate, which is meaning the schema cannot convey.

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?

States a specific verb (delete), resource (candidate) and scope (and all their applications), plus the irreversible nature. It also distinguishes itself from the sibling anonymize_candidate by naming it explicitly, so an agent can route correctly without opening either schema.

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?

Gives an explicit prerequisite chain for obtaining the required ID (search_candidates_by_name then get_candidate) and an explicit when-to-use-the-alternative condition ('For GDPR compliance, consider anonymize_candidate instead'). This is exactly the routing guidance an agent needs.

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?

With no annotations provided, the description carries the full burden and does so well: it discloses that the operation is destructive, irreversible ('cannot be undone'), cascades to all values, and requires admin permissions. These are exactly the behavioral traits an agent needs before invoking a delete tool.

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 front-loaded and tightly structured: purpose first, then critical safety/permission warnings, then a parameter lookup hint. Every sentence earns its place with no 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?

For a simple one-parameter delete tool with an output schema available, the description covers purpose, destructive irreversibility, permission requirements, and parameter acquisition. 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?

The schema fully documents the single custom_field_id parameter, so the baseline would be 3. The description adds useful meaning beyond the schema by explaining how to find the ID via list_custom_fields and name matching, which improves invocation accuracy.

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: 'Delete a custom field and all its values.' It clearly distinguishes this operation from siblings like update_custom_field and create_custom_field by focusing on deletion, and the scope of deleting all values is made explicit.

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 provides clear context: 'Admin only' states a prerequisite, and 'To find custom_field_id: list_custom_fields → match by name' gives procedural guidance for obtaining the required parameter. However, it does not explicitly state when not to use this tool or name alternatives such as delete_custom_field_options for deleting only field options.

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?

With no annotations, the description carries the full burden and does so well: irreversible destructive operation, admin-only permission requirement, the side effect that historical selections retain the now-inactive option, and a 50-option threshold that switches to asynchronous bulk processing.

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?

Front-loads the action and its destructive/admin nature before the ID-resolution instructions. Dense and largely waste-free, though the telegraphic arrow notation is slightly terse.

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?

An output schema exists so return values need not be explained, and the description still covers the async-bulk edge case (with get_bulk_request_status available as a sibling). An agent has everything needed 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 coverage is 100%, so baseline is 3, but the description adds lookup provenance by naming the exact tools that produce custom_field_id and option_ids. It adds no array-size or ID-format detail beyond that.

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?

States a specific verb+resource (delete dropdown options from a custom field) and immediately marks it destructive and admin-only. It is clearly distinguishable from siblings like update_custom_field_options, delete_custom_field, and list_custom_field_options.

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?

Gives explicit prerequisite routing: use list_custom_fields to resolve custom_field_id and list_custom_field_options to resolve option_ids, both by name. It does not explicitly contrast when to delete vs. deactivate/update an option, so it stops short of full when/when-not 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?

With no annotations supplied, the description carries the full burden and does disclose the two most important traits: this is a write operation and it 'cannot be undone'. That is real destructive-behavior disclosure beyond a bare verb. It still omits permission requirements and side effects (candidate notification, fate of attached scorecards/feedback), 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?

Two short, front-loaded sentences: the action and its irreversibility come first, the ID-sourcing hint second. Nothing is padding, and the most decision-relevant fact (cannot be undone) is not buried.

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?

An output schema exists so return values need no explanation, and the single-parameter surface is fully covered. The description supplies purpose, destructiveness, and ID sourcing. The remaining gap is a subtle naming mismatch — the tool is delete_interview but the description says 'cancel', leaving the agent unsure whether the record is removed or merely marked cancelled.

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%, so the baseline is 3, but the description adds actionable meaning: it tells the agent that interview_id is the scheduled interview ID and, more importantly, how to obtain one via list_interviews_for_application on the candidate's application. That is genuinely useful retrieval guidance rather than restating 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?

States a specific verb and resource ('Cancel a scheduled interview') and is immediately distinguishable from sibling read/write interview tools like get_interview, list_interviews, or update_interview. It also names a sibling (list_interviews_for_application) so the agent can place the tool in the workflow.

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?

Clearly conveys when to reach for this tool (cancelling a scheduled interview) and gives an explicit path for sourcing the required ID via list_interviews_for_application. It stops short of naming the alternative for non-destructive changes (e.g., update_interview to reschedule instead of cancel), so there are no explicit exclusions.

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?

With no annotations provided, the description carries the full behavioral burden. It discloses the critical irreversibility ('Destructive — cannot be undone'), but does not mention required permissions, side effects on related applications, or failure conditions.

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 two tight sentences: the destructive warning is front-loaded, and ID discovery instructions follow immediately. 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?

Given the destructive mutation, no annotations, and an output schema that handles return values, the description covers the action, irreversibility, and ID lookup. However, it omits authorization requirements and side effects that an agent should know before deletion.

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%, so the baseline is 3. The description adds value beyond the schema by explaining how to discover the required job_id (via list_jobs, matched by name) and opening_id (via list_job_openings on the job).

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 and resource: 'Delete a job opening.' It is clear what the tool does, though it does not explicitly contrast itself with bulk_delete_job_openings or other sibling deletion 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 provides helpful prerequisite guidance for obtaining job_id and opening_id, but it does not state when to use this tool instead of alternatives such as bulk_delete_job_openings or delete_candidate.

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?

No annotations are provided, so the description carries the full disclosure burden, and it does deliver the most important trait: "Destructive — removes it from all candidates," making the blast radius explicit. It stops short of stating irreversibility, required permissions, or behavior when the tag does not exist.

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 short lines, zero waste, with the destructive nature and scope front-loaded ahead of the procedural ID-lookup hint. Every sentence earns its place.

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 delete with an output schema, the description covers the essential scope and the prerequisite lookup. Missing only edge-case behavior (nonexistent tag, error semantics), which is a minor gap at this complexity.

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?

With one parameter and 100% schema description coverage, the schema already documents tag_id and even the list_tags lookup path, so the description largely repeats structured data. Baseline 3 is appropriate; no additional syntax or constraint detail is added.

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?

States a specific verb+resource ("Delete a tag") and pins the scope to "from the organization," which cleanly separates it from the sibling remove_tag_from_candidate (per-candidate removal) and from delete_candidate. An agent can pick the right tool without opening the schema.

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 routes the agent to list_tags for obtaining tag_id and implies the org-wide blast radius, which hints at why one would choose this over remove_tag_from_candidate. However, it never explicitly states when to use this tool versus that sibling, so usage is inferred rather than spelled out.

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?

With no annotations, the description carries the full burden, and it does disclose that this is a mutation, that it is reversible via enable_user, and that it returns {"success": true}. It stops short of stating required permission level or side effects beyond login blocking (e.g. session termination, notification), so it is strong but not exhaustive.

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?

Very short and front-loaded: purpose first, then lookup workflow, then reversibility and return shape. No filler sentences; every line carries usable information.

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 one-parameter mutation with an output schema, the description covers purpose, effect, ID discovery, reversibility, and a return summary. Nothing an agent needs to invoke it correctly 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 100% and the single parameter is documented as "Greenhouse user ID to disable", so the baseline is 3. The description goes beyond the schema by explaining how to obtain the ID (list_users → match by name or email), which is genuine added value for the one parameter.

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?

States a specific verb+resource ("Deactivate (disable) a Greenhouse user") plus the concrete effect ("preventing login"), and labels it a write operation. This clearly distinguishes it from siblings like enable_user and the various list/get user 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?

Provides a natural-language trigger ("deactivate John's account"), an explicit prerequisite workflow for obtaining user_id (list_users → match by name or email), and names the reversing tool (enable_user). The agent is routed to the correct alternatives rather than having to infer them.

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?

No annotations are provided, so the description carries full disclosure burden. It declares 'Read-only' and adds genuinely useful behavior beyond structured data: attachment URLs are time-limited and a failed download should be retried by re-fetching the record for a fresh URL. It stops short of detailing response content types or auth requirements, but the core operational trait is disclosed.

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 tight paragraphs, purpose front-loaded first, followed by usage and the retry caveat. No repetition or filler; every sentence earns its place.

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 an output schema present, return-value explanation is unnecessary. The description covers purpose, source of the URL, and the retry-on-expiry behavior, which is everything an agent needs to invoke this single-parameter read 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%, so the baseline is 3. The description goes beyond the schema by stating the URL is time-limited and should be re-obtained on failure, which adds real semantic meaning about the parameter's lifecycle that the schema description does not convey.

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?

States a specific verb (download) and resource (content from a Greenhouse attachment URL), which is distinct from every sibling. An agent can immediately tell this is a content-fetch operation, not a metadata list or mutation.

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?

Tells the agent exactly when to use it — 'when you have a specific attachment URL from a candidate or application record' — and cites the sources (get_candidate/get_application attachments arrays). It does not name explicit exclusions or alternatives, but the usage context is unambiguous.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that this is a write operation and returns {"success": true} on success, but it does not cover permissions required, side effects, error cases, or whether the operation is idempotent.

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 front-loaded with the purpose and operation type, then gives a concrete lookup instruction and the return shape. Every sentence is short and earns its place, with no redundant or filler content.

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 simple one-parameter enable tool with a full input schema, an output schema, and no annotations, the description is largely complete. It covers purpose, mutation behavior, how to find the required ID, and the success response, though it omits permission or side-effect details.

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%, so the schema already documents the single user_id parameter. The description adds meaning beyond the schema by explaining how to obtain the required ID: use list_users and match by name or email. That is useful operational context not present in the input 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 states a specific verb and resource: 'Re-activate (enable) a previously deactivated user.' It also labels the operation as a 'Write operation,' which clarifies it is not a read or update. However, it does not explicitly distinguish this tool from its closest sibling, disable_user, or explain why an agent should choose this over a general user update.

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?

Usage is implied by 'previously deactivated user,' and the description gives practical prerequisite guidance for finding user_id via list_users. It does not, however, state when to use this tool versus alternatives such as disable_user or update_user, nor does it include any exclusions or conditions.

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?

With no annotations the description carries the full burden, and it delivers the two most important traits: it declares 'Read-only' up front and notes that include_candidate_details 'adds API calls', a cost signal. It omits auth/permission requirements and any pagination or result-limit behavior, which keeps it below 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?

Front-loaded with the core definition, then the example query, then parameter notes — a sensible order. Every sentence is useful, though the return-value sentence partly duplicates the output schema.

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 an output schema present the description needn't explain return values, yet it still summarizes the grouping. Combined with 100% schema coverage, read-only disclosure, and clear parameter intent, an agent has enough to call it correctly; only auth and pagination context are 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 100%, so the baseline is 3, but the description adds real meaning: it clarifies the inclusive boundary ('applications created on or after it') and gives a workflow hint for job_id ('list_jobs → match by name'). It does not address the status parameter, so it does not fully rise to 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?

States a specific verb and resource ('Applications since a date, grouped by job') and frames the use case as 'the daily digest'. It is clear what the tool does, but it never names the sibling it is not (e.g. list_applications, get_activity_feed), so an agent must infer the boundary itself.

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 embedded user question ('what new applications came in since yesterday?') gives a concrete when-to-use context, and it explains the since and job_id usage. It stops short of explicit exclusions or naming an alternative tool, so it is clear context without routing 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?

No annotations exist, so the description carries the full burden, and it does well: it declares 'Read-only,' describes the return shape (three lists, newest first), and enumerates entry fields. It omits permission/auth requirements and any pagination or result-size behavior, which keeps it short of 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?

Front-loaded with the core purpose and read-only note, followed by trigger examples and return structure. Some return-field detail is arguably redundant given an output schema exists, but the text is dense and free of 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 read-only, two-parameter lookup, the description plus schema and output schema cover everything an agent needs to call it correctly. Nothing critical is missing, though it could note pagination or entry-volume behavior for large candidate histories.

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%, so the schema already documents both parameters. The description adds genuine meaning beyond the schema by telling the agent to resolve candidate_id via search_candidates_by_name, though it says nothing extra about created_after.

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?

States a specific verb and resource ('Get a candidate's activity timeline') and reinforces scope with 'Read-only.' An agent can distinguish this from list_candidates, get_candidate, or add_note_to_candidate without opening any schema.

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 concrete trigger phrasing ('show me Sarah's history', 'what's happened with this candidate?') and routes the agent to search_candidates_by_name for resolving candidate_id. It lacks explicit when-not-to-use or named alternatives for timeline-style queries, but the positive usage context is clear.

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