Recruitee MCP by usefulapi

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

Annotations only declare destructiveHint=true, so the description's explicit 'WRITE:' marker usefully confirms this is a mutation rather than a read. The 'visible to the team' clause adds real behavioral context about visibility that no structured field conveys. It still omits reversibility, permission requirements, and the fact that adding a note does not obviously match the destructive hint's implication.

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 sentences with the mutation marker and API endpoint front-loaded and zero filler. Every clause carries information an agent can act on.

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, no-output-schema write tool, the description covers the action, the target, visibility, and the backing endpoint. The only gap is the absence of any guidance on when this is the right tool versus sibling write operations.

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% and both parameters (candidate_id, body) are documented with types, bounds, and descriptions in the schema. The description only alludes to the target ('a candidate's profile') and adds no format, length, or content guidance beyond the schema, 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 a note to a candidate's profile') and adds the scope qualifier 'visible to the team'. This clearly separates it from the sibling recruitee_list_candidate_notes (read) and other candidate-mutation 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 says what happens but never when to reach for this tool versus alternatives such as recruitee_add_candidate_tags, recruitee_update_candidate, or recruitee_create_task. No prerequisites or exclusions are given, so usage must be inferred from the name alone.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the burden; it discloses the key side effect that unknown tag names are created as new tags while known names are reused. It does not mention permissions or error/limit behavior, but the central behavioral trait is covered.

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 sentences with the WRITE marker front-loaded and the endpoint reference last; every clause carries 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 a 2-param mutation with no output schema, the description covers the action, side effects, and payload shape. It stops short of return/confirmation format and permission requirements, which 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% and the schema defines both params, so baseline would be 3; the description adds real meaning by explaining that 'tags' entries are matched by name and may create new tag entities, 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+resource ('add one or more tags to a candidate') and even names the transport endpoint. It is easily distinguished from siblings like recruitee_add_candidate_note or recruitee_update_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?

Usage is implied by the mutation semantics, and the note about reusing existing tags vs creating new ones hints at when it matters, but there is no explicit when-to-use/when-not guidance or reference to alternatives such as recruitee_list_tags for discovery.

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

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

Annotations only declare destructiveHint=true; the description adds meaningful context by labeling the operation WRITE and describing the side effect (a placement created in the pipeline's first stage). It stops short of covering idempotency, behavior when the candidate is already placed, or permission requirements.

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, front-loaded with the WRITE classification and the core effect, with the parameter constraint immediately after. The endpoint reference is compact and useful for error mapping; 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 no output schema, the description carries the return burden but reasonably implies a created placement. It covers the XOR constraint and the write effect, missing only edge-case behavior (already-placed candidate, failure modes) which is a minor gap for a 3-param 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 exclusive-or semantics between offer_id and talent_pool_id that the schema does not express — both are optional there, so an agent could otherwise pass neither. That constraint is genuinely load-bearing beyond the structured data.

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 ('put an existing candidate on a job') and scopes it precisely: creates a placement in the pipeline's first stage. 'existing' distinguishes it from recruitee_create_candidate, and 'first stage' distinguishes it from recruitee_move_candidate_stage.

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 selection rule ('Pass exactly one of offer_id or talent_pool_id') and silently establishes the precondition that the candidate must already exist. It does not name sibling alternatives for the move-vs-assign decision, 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?

The description goes beyond the destructiveHint annotation by disclosing that no auto-confirmation email is sent and that assigned jobs default to the job's default stage. These are meaningful behavioral facts an agent cannot get from annotations or schema, though it doesn't cover return values (none exist) or list-limit behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence plus a short endpoint reference, front-loading the WRITE marker and core purpose with no filler. Slightly dense but 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 creation tool with full schema coverage and no output schema, the description covers the key behavioral nuance (no confirmation email, default-stage assignment) and the endpoint. It leaves minor gaps around error behavior and the exact effect of offer_ids, but is sufficient for 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 parameters are already documented in the schema. The description adds the notion that offer_ids map to jobs/talent pools and default-stage assignment, but does not add syntax or format detail beyond the schema. 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 (create/add) and resource (candidate), and the parenthetical clarifies the exact creation mode: manual entry as if a recruiter added them, distinguishing it from an import or application-driven flow. An agent can distinguish it from recruitee_update_candidate or recruitee_add_candidate_note without further inspection.

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 that the candidate is added manually with no auto-confirmation email sent, which is clear context for choosing this over an application-based flow. It does not explicitly name or contrast with siblings like recruitee_assign_candidate_to_offer, so it stops short of full alternative 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?

The 'WRITE:' prefix and the POST endpoint disclosure align with the destructiveHint annotation, but largely restate what structured data already conveys. It adds the cross-tool dependency for admin ids, yet says nothing about required permissions, whether the task is immediately visible/notified to assignees, or what happens on invalid candidate_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?

Two tight sentences with the operation class front-loaded and the endpoint trailing. No filler; every clause carries load.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should stand alone for a 6-parameter create tool, and it does cover purpose, key inputs, and the id-source dependency. It omits return shape and any error/permission behavior, 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema lacks: that candidate association is optional, that admin_ids must come from recruitee_list_team_members, and that due_date is optional. The due_date/timezone coupling is left 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 ('create a recruiting task') plus scope modifiers (optional candidate link, team-member assignment, optional due date). It is clearly distinguishable from siblings like recruitee_list_tasks or recruitee_create_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 'WRITE:' prefix signals the operation class, and the parenthetical '(admin ids from recruitee_list_team_members)' tells the agent where to obtain valid assignee ids before calling. It does not state exclusions (e.g., when to prefer updating an existing task), so it stops short of a 5.

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

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

The readOnlyHint annotation already establishes this as a safe read. The description adds valuable behavioral context by disclosing the returned profile contents, including placements with their placement id and current stage. It does not cover auth, rate limits, or missing-candidate behavior, but those are less critical for a simple read 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?

The key purpose is front-loaded, and the description is compact despite enumerating many returned fields. The endpoint reference is somewhat redundant but not distracting, and the field list earns its place because there is no 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 no output schema, the description carries the return-shape burden and does so by enumerating the profile fields and placement structure. It also highlights the placement id needed for recruitee_move_candidate_stage, which is important cross-tool context. ReadOnlyHint covers the safety profile, leaving no major gaps for a simple get-by-id 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 the baseline is 3. The single candidate_id parameter is fully documented in the schema; the description does not add format, constraints, or alternative identifier details 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: fetch one candidate's full profile by candidate_id. The singular 'one candidate' and 'full profile' distinguish it from list_candidates and search_candidates. It also enumerates the returned profile sections, making the tool's scope concrete.

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 'Fetch one candidate's full profile,' but the description does not say when to choose this over list_candidates, search_candidates, or update_candidate. It usefully notes that the placement id is needed by recruitee_move_candidate_stage, which is downstream context rather than an explicit when-to-use rule.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that: it enumerates the returned fields (name, email, role, role abilities, company id) and gives the underlying endpoint (GET /c/{company_id}/admin), which helps the agent reason about scope and cost.

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, front-loaded with what is fetched and what it returns, followed by the practical reason to call it. Every clause earns its place with no repetition of the name or title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing return values and does so by listing the fields returned. For a zero-parameter read tool with a readOnlyHint annotation, 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?

The tool takes zero parameters, so per the baseline this scores 4. The description's mention of company_id is contextual (it appears in the endpoint path) rather than a required input, so no additional parameter meaning is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetch) plus a precisely scoped resource: the Recruitee user the API token belongs to, enumerated by returned fields (name, email, role, role abilities, company id). This is clearly distinguishable from siblings such as recruitee_list_team_members, since it returns the token's own identity rather than a team roster.

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-to-use context — 'a cheap way to confirm the token and company id are right' — which tells the agent this is a cheap verification call rather than a data-gathering step. It does not name an alternative tool or a when-not-to-use condition, so it stops short of a 5.

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

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

readOnlyHint=true already signals a safe read, and the description adds value by spelling out the returned detail set (description, requirements, salary, candidate counters, pipeline_template_id), which matters because there is no output schema. It does not mention auth or error behavior, but the annotation lowers the bar.

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, front-loaded with the action and scope, followed by the enumerated return fields and the underlying endpoint. 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 one-parameter read-only tool with no output schema, the description covers the essentials by listing what the response contains and citing the REST endpoint. Minor gaps around id source and error handling keep 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% and the single offer_id parameter is fully documented there. The description's phrase 'by id' adds nothing beyond the schema, so the baseline of 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 (Fetch) and resource (one job or talent pool by id) and enumerates the detail fields returned, which clearly sets it apart from the plural recruitee_list_offers. It stops short of explicitly naming the sibling it complements, so it is clear but not maximally differentiated.

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 only implied: fetch a single offer when you already have its id. There is no statement of when to prefer this over recruitee_list_offers or how the id is obtained, and no exclusions or prerequisites.

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?

readOnlyHint=true already signals a safe read; the description goes further by disclosing the return shape (ordered stages) and the inter-tool id flow. It adds no auth/rate-limit context, but for a read-only fetch the added return-content detail is meaningful value beyond the annotation.

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 tight sentences, front-loaded with the action and return fields, then the id chain, then the underlying endpoint. 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?

With no output schema, the description carries the burden of describing returns and does so (ordered stages with id, name, group, category). It also names the exact API endpoint, making it complete for a single-param fetch tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that pipeline_template_id is sourced from list_offers/get_offer, enriching the otherwise terse schema description 'The pipeline template 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?

States a specific verb and resource ('Fetch a pipeline template with its ordered stages') and enumerates the returned fields (id, name, group, category). It distinguishes itself from siblings by explaining where the id comes from and which tool consumes the stage ids.

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 workflow context: the pipeline_template_id originates from recruitee_list_offers / recruitee_get_offer, and the stage ids feed recruitee_move_candidate_stage. It does not state explicit when-not-to-use exclusions, but the dependency chain is well articulated.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds genuinely useful behavioral context by disclosing what each note carries (replies, author admin_id, visibility), but says nothing about pagination, ordering, or auth/company scoping.

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?

One front-loaded sentence describing purpose and returned fields, plus a compact endpoint reference. No filler and nothing that could be trimmed without losing 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?

With no output schema, the description usefully enumerates the returned note fields, and annotations cover the safety profile. Only minor gaps remain (pagination and ordering behavior for a list operation), so it is close to complete for a one-parameter read 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?

There is a single required parameter and schema description coverage is 100%, so the schema already documents candidate_id fully. The description adds no extra meaning (format, source, or constraints) beyond the schema, which is the expected baseline.

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 ('List') and resource ('notes on a candidate's profile') and even names the underlying endpoint, GET /c/{company_id}/candidates/{candidate_id}/notes. Together with the name it clearly separates the read counterpart from the sibling recruitee_add_candidate_note.

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 says what is listed but never says when to reach for it versus alternatives such as recruitee_get_candidate or recruitee_list_evaluations, nor any prerequisite (e.g. needing a valid candidate_id from a prior lookup). Usage is only implied by the verb 'List'.

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

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

Annotations only declare readOnlyHint=true; the description adds genuinely new behavioral context by specifying default ordering and the pagination contract (next offset = offset + limit). It doesn't state response shape, page-item structure, or rate limits, but for a read-only list the added pagination contract is substantive.

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, front-loaded with the core action and default ordering, then filters and pagination. The trailing API endpoint note is compact and no sentence 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?

For a 9-parameter read-only list tool with no output schema, the description covers all invocation-relevant concerns: filtering options, ordering, and pagination. It leaves out the 'sort' alternative and any hint of the returned item structure, which are minor given the schema documents every parameter.

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 adds value beyond the schema by spelling out the pagination arithmetic (next offset = offset + limit), which the offset/limit descriptions do not explain, though it omits mention of the 'sort' option (by_last_message) that the schema exposes.

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 ('List candidates') plus scope details: default ordering (newest first) and the full set of narrowing options. It does not differentiate from the close sibling recruitee_search_candidates, whose function overlaps with the 'name/job search' filter described here, 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?

Gives clear context for use: enumerates the narrowing conditions (one job, name/job search, qualified/disqualified, specific ids, created after a date) and explains pagination mechanics. It never states when to prefer this over recruitee_search_candidates or recruitee_get_candidate, so no exclusions or alternatives are offered.

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?

readOnlyHint=true already declares this is a safe read, lowering the bar. The description adds useful context by disclosing exactly what comes back (ids and job counts), but says nothing about pagination, scope limits, or whether departments without jobs appear.

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 sentences with the resource and return contents front-loaded and the endpoint reference trailing as supporting detail. 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 no parameters and no output schema, the description carries the return-shape burden and discharges it by naming ids and job counts. A note on ordering or pagination is the only meaningful gap for such a simple read 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?

Zero parameters, so the schema_description_coverage baseline of 4 applies. There is nothing for the description to disambiguate and it correctly introduces no parameter discussion.

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 ('List the company's departments') and goes further by naming the returned fields ('their ids and job counts'). The resource is distinct from siblings like list_team_members and list_tags, though the description never explicitly contrasts itself with them.

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?

No guidance on when to use this versus alternatives, nor any prerequisites. The API endpoint reference implies direct REST correspondence but tells the agent nothing about selection context.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the underlying endpoint (GET /c/{company_id}/disqualify_reasons) and the shape of the returned records, which is the main behavioral fact an agent needs here.

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 sentences, with the core purpose front-loaded and the use case second. The trailing endpoint reference is slightly technical but compact and arguably useful for traceability, so no real waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing with no output schema, the description supplies what's needed: what it returns, what it's for, and the API path. Only minor omissions (e.g., whether the list is complete or paginated) keep it shy of 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description correctly doesn't waste space on parameter talk.

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 ('List the company's configured disqualification reasons') and even enumerates the returned fields (id, name, position). No sibling tool covers disqualification reasons, so an agent can route to it unambiguously.

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 a contextual use case ('useful for reading why candidates were disqualified'), which implies when to reach for it. However, it names no alternatives or prerequisites (e.g., that a reason id is needed to disqualify a candidate elsewhere), so guidance remains implicit 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the upstream endpoint (GET /c/{company_id}/interview/results) and the shape of what comes back conceptually, but says nothing about pagination semantics, defaults, or volume/rate behavior beyond what the schema already states.

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?

A single dense sentence front-loads the resource and its disambiguation, followed by a compact endpoint reference. Nothing is wasted, though the em-dash aside and trailing endpoint citation make it slightly denser than an ideal two-beat structure.

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?

There is no output schema, so the description must carry some of the return-value burden, and it does sketch the two result types (evaluations with rating + note, questionnaire scorecards). For a 6-param, zero-required read tool this is largely sufficient, with only return format/pagination detail left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter (kind, page, limit, scope, admin_ids, candidate_id) is already documented with defaults and enums in the schema. The description only loosely gestures at the candidate and reviewer filters, adding no syntax or format detail beyond the schema, so the 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?

Specific verb (List) plus resource (interview results/evaluations) with an in-line gloss of what an evaluation actually contains (rating + note) and that questionnaire scorecards are included. It distinguishes itself implicitly from recruitee_list_interview_events by naming results rather than events, but it does not explicitly contrast with any sibling, 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?

"Optionally for one candidate or by selected reviewers" hints at the two filtering modes, which maps loosely to candidate_id and admin_ids. However, there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. list_interview_events), 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?

The readOnlyHint annotation already covers the safety profile, so the description's added value is the default scope disclosure: whole-company upcoming events unless narrowed. That is a genuine behavioral trait affecting what the agent receives, not a restatement of the annotations. It does not touch on pagination or rate/auth behavior, so a 4 rather than 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 tight sentences plus an endpoint reference; the resource and returned fields come first, then the default and narrowing behavior. Every clause 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 a nine-parameter, zero-required filter tool with no output schema, the description covers the resource, the returned fields, the default scope, and the narrowing dimensions — enough for an agent to call it correctly. Minor gaps (timezone/date-range coupling, interaction of page/limit) are handled by the schema, but the description could have surfaced them.

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%, and the schema already states the 'default all' scope and 'default upcoming' status, so the description's default statements largely repeat structured data. The hint about narrowing by candidate/date range/interviewer loosely maps to candidate_id, start_date/end_date, and admin_ids but adds no syntax or format detail (e.g., timezone interaction with date range). 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?

The description names a specific verb and resource ('List scheduled interview events') and then enumerates the returned fields (candidate_id, offer_id, stage_id, start time, duration, location, attendees), which pins down exactly what data an agent will get. It even cites the underlying endpoint, leaving no ambiguity about what this tool does versus the candidate/offer/task tools in the sibling list.

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?

'Defaults to upcoming events for the whole company; narrow by candidate, date range or interviewer' tells the agent the default behavior and the axes it can filter on, which is actionable context. It stops short of naming when NOT to use this tool or pointing to an alternative for past/other interview data, so it falls just below the explicit when/when-not bar.

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

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

Annotations only declare readOnlyHint=true, so the description adds real behavioral context beyond the structured fields: default page size of 1000, the limit+page pagination model, and the fact that meta.total_count carries the total. It stops short of noting rate limits or ordering guarantees.

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 scoping, then packs filtering, includes, pagination and the underlying REST path into a few dense sentences. The field enumeration is slightly long, but every clause carries actionable 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?

With no output schema, the description carries the burden and does list the returned fields plus meta.total_count, so an agent knows the response shape. Multi-dimensional filters are all enumerated. It is complete enough for a 14-parameter list 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 baseline is 3, but the description adds meaning beyond the schema by naming the default returned fields and clarifying what `include` unlocks (counters for candidate counts, description, salary, location_ids). This supplements the schema's own enum list with intent.

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 ('List the company's jobs') and resolves the domain naming ambiguity by clarifying that Recruitee calls jobs 'offers'. An agent can distinguish this list tool from the sibling recruitee_get_offer 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?

The description enumerates filtering dimensions ('Filter by status, department, location, recruiter, hiring manager, tag and more'), which implies when the tool is useful, but it never states when to prefer it over alternatives like recruitee_get_offer for a single job or the candidate-search siblings. Usage is implied rather than directed.

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?

readOnlyHint=true already declares this is a safe read, so the burden is reduced. The description adds that the response includes ids and usage counts, which is useful context the annotations don't carry, but it says nothing about pagination, result limits, or whether tags are company-scoped.

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 sentences plus an endpoint reference, front-loaded with the core purpose and the downstream-use hint. The trailing 'Recruitee: GET /c/{company_id}/tags.' is mildly redundant but harmless.

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 list tool with full schema coverage and no output schema, the description covers purpose, output shape (ids and counts), and the downstream consumer. Missing only pagination/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 query, sort_by, and sort_order are already documented. The description adds no parameter detail beyond what the schema provides, making the baseline 3 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 ('List the company's candidate tags with ids and usage counts') and distinguishes itself from siblings by noting the ids feed recruitee_search_candidates filters. An agent can pick this over recruitee_list_candidates or recruitee_add_candidate_tags 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?

Explicitly ties the tool's output to a downstream use case (tag ids used in recruitee_search_candidates filters), which tells the agent when to reach for it. It does not state when-not to use it or a clear alternative for tag lookup, 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?

readOnlyHint already declares this a safe read. The description goes beyond that by naming the underlying Recruitee endpoints and disclosing the parameter-applicability rule for each mode, which the annotations do not cover. It stops short of describing pagination defaults or result ordering guarantees, 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?

Two dense sentences, front-loaded with the resource and returned fields before the mode-dependent branching and endpoint references. No filler, and parenthetical endpoint details are tucked away rather than cluttering the primary instruction.

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, no-required-args list tool with no output schema, the description covers both modes, the returned field set, and which parameters are honored where. It omits pagination behavior and default ordering, which would matter for an agent assembling multi-page reads, keeping it just short of fully 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 description coverage is 100% and each parameter already carries a 'company list only' note, so the schema does the heavy lifting. The description reinforces which parameters apply in which mode but adds no format, default, or inter-parameter semantics beyond that. 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 ('List recruiting tasks') and immediately enumerates the returned fields (title, description, due date, completed, candidate_id). It also crisply separates the two retrieval modes (per-candidate vs company-wide), so an agent knows exactly what this tool returns and how it differs from a single-path list tool.

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 states the branch condition: pass candidate_id to get one candidate's tasks, omit it to get company tasks. Critically, it warns that in candidate mode 'only `status` applies', preventing the agent from sending scope/sort/page to an endpoint that ignores them. That is exactly the when-to-use/when-not 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 readOnlyHint=true, the safety profile is already covered, yet the description adds real value: it discloses that records are memberships, that names/emails live in a separate `references` array, and maps to the underlying GET endpoint. This output-shape detail is important since no output schema exists.

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 tight sentences, front-loaded with the core purpose followed by usage guidance and the endpoint mapping. No filler, though the trailing API-endpoint note is marginally 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?

Annotations cover safety and no output schema exists, so the description carries the return-value burden and does so reasonably by listing key fields and the `references` array. It stops short of describing pagination behavior, which is a minor gap for a paginated list 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 page, limit, query, role_id, sort_by and sort_order are all documented in the schema. The description only mentions admin_id, which is a returned field rather than an input parameter, so it adds nothing beyond the schema. 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 ('List the company's team members (memberships)') and enumerates the returned fields (admin_id, role, recruiter/hiring-manager status, accessible jobs). No sibling in the list competes for this resource, so the agent can identify it unambiguously.

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?

'Use admin_id values for task assignees and filters' gives concrete downstream guidance on what to do with the results, which is valuable context. It does not name when-not-to-use conditions or alternatives, but no comparable sibling exists to route against.

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

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

Annotations only supply destructiveHint=true; the description goes further by disclosing that stage automations configured in Recruitee may run as a side effect and that the operation is reversible by moving back. It does not mention permission requirements or any rate limits, which keeps it short of a full behavioral picture.

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 WRITE nature and the core action, then layers id sources, the conditional param, side effects, undo, and the underlying endpoint in four tight sentences. No filler or restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and only three flat parameters, the description covers everything needed to invoke the call correctly: ids, their sources, the conditional work_location_id, side effects, and reversibility. The one gap is that it never says what the response contains (e.g., the updated placement/stage), which an agent would otherwise have to discover empirically.

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 value beyond the schema by telling the agent WHERE to obtain each id (get_candidate placements, get_pipeline_template) and emphasizing that placement_id is per-job rather than the candidate id. It clarifies the ambiguity around one of the two required params.

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 to another stage of a job's pipeline,' prefixed with WRITE. No sibling competes for this action (the closest, assign_candidate_to_offer and update_candidate, target different resources), so an agent can select it unambiguously.

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 preconditions and the exact source of each id (placement id from recruitee_get_candidate → placements[].id; stage id from recruitee_get_pipeline_template), plus the conditional rule that a 'hired' destination needs work_location_id. It lacks an explicit when-not statement, but for a tool with no alternative sibling that is a minor omission.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description earns credit by disclosing the return shape ('hits' with each candidate's placements and 'total') even though no output schema exists, and by naming the underlying endpoint. It stops short of describing pagination behavior despite page/limit params.

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?

Well front-loaded: purpose first, then query semantics, then filter examples, then return shape. Every sentence carries information, though the trailing raw API endpoint reference is the least valuable line.

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 search tool with no output schema, the definition covers the essentials: what is searched, how filters are shaped, and what comes back (hits + total, with placements). 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?

Although schema coverage is 100%, the description adds meaning the schema cannot: it spells out which fields free-text `query` covers and expands the opaque filter-object format with four concrete examples (created_at Unix seconds, has_cv boolean, tags, stages). That is essential guidance beyond the bare 'additionalProperties' 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 gives a specific verb+resource ('Search the company's candidates') and elaborates on exactly what `query` scans across, which makes the tool's scope unambiguous. It does not, however, explicitly differentiate itself from the sibling `recruitee_list_candidates`, so it lands one notch below the top.

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 signals when this is the right tool by describing it as 'the same engine as the app's filters' and showing filter examples, implying use when filtering/searching is needed. But it never states when to prefer `list_candidates` or `get_candidate` instead, leaving the agent to infer the boundary.

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

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

Annotations only declare destructiveHint=true, so the description carries real weight: it discloses PATCH partial-update semantics ('only the fields you pass change') and the genuinely dangerous list-replacement behavior ('pass the full list you want'), which an agent could otherwise get wrong and silently wipe emails/phones/links. It also names the underlying endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no padding, front-loaded with the operation type and the destructive-replacement warning before the endpoint detail. Every clause 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 7-parameter mutation with annotations covering destructiveness and no output schema, the description supplies what matters most: partial-update semantics and list-overwrite risk. It omits auth/permission requirements and does not mention the uncovered cover_letter field, leaving a small 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% and each list parameter already says 'Full replacement list', so the baseline is 3. The description goes a step further by consolidating the partial-update rule and warning that omitted fields are untouched while passed lists overwrite, which is a semantic contract the schema does not state field-by-field.

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 (update) and resource (candidate) plus the field scope (name/contact details), which cleanly separates it from recruitee_create_candidate and recruitee_get_candidate. The scope statement slightly understates the schema, since cover_letter is also updatable, but the core purpose is unambiguous.

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 'WRITE:' prefix signals a mutation, which implicitly routes an agent away from the read siblings, but there is no explicit when-to-use guidance, no mention of reading first via recruitee_get_candidate, and no note about when to prefer the tag/note/stage siblings.

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