recruitee

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 and does add real context: it is a write, the note becomes 'visible to the team', and it maps to the documented notes endpoint. It still omits whether the operation appends vs. overwrites and any auth/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?

A single compact sentence with the write nature front-loaded in a 'WRITE:' prefix, followed by the resource and 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?

There is no output schema, and the description does not say what is returned after creating the note, but the required parameters and endpoint are covered and the visibility semantics are stated. Adequate for this simple two-parameter write.

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 (body, candidate_id) are already documented with types and constraints, so the description adds no 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 and resource ('add a note to a candidate's profile') plus the exact API endpoint, so the action is unambiguous. It is trivially distinguishable from the sibling list_candidate_notes, which reads rather than writes.

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 implies this is the mutation path for candidate notes, but there is no explicit when-to-use or when-not, no mention of prerequisites (e.g., the note body must be non-empty, per the schema), and no named alternative.

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?

Goes beyond the single destructiveHint annotation by disclosing the key side effect: existing tags are reused by name while new names create new tags. That is exactly the behavior an agent needs to predict the mutation's impact. It does not mention failure modes (nonexistent candidate, tag limit) or normalization rules.

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 clauses with the WRITE marker and the core semantics front-loaded; nothing is redundant. The trailing REST endpoint adds marginal value for an agent that does not call the API directly, but is not wasteful enough to penalize heavily.

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 mutation with no output schema, the description covers the operation, the tag-reuse behavior, and the write nature. Remaining gaps (error behavior, whether additions are idempotent) are minor for this complexity level.

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 already 100%, so the baseline is 3, but the description adds real meaning about the tags parameter: it can take multiple values and unknown names will spawn new tags rather than fail. That resolves the main ambiguity about tag resolution.

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 an explicit verb+resource ("add one or more tags to a candidate") and tags the operation as WRITE. This cleanly separates it from siblings like recruitee_add_candidate_note or recruitee_update_candidate without needing 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?

Usage is implied by the WRITE framing and the tool name, but there is no explicit when-to-use guidance, no mention of prerequisites (candidate must exist, auth scope), and no reference to alternatives such as recruitee_update_candidate or recruitee_list_tags.

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 supply destructiveHint=true; the description reinforces the mutation nature with 'WRITE:' and adds genuinely new behavior — it creates a placement in the pipeline's FIRST stage and names the underlying POST endpoint. It omits failure/idempotency 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?

One dense sentence, front-loaded with the WRITE prefix and the core action, then the key constraint and endpoint. 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 3-param write tool with no output schema, the description covers what it does, the one-of constraint, the pipeline placement behavior, and the endpoint. Nothing essential for 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 schema already explains each id. The description adds the mutual-exclusivity rule 'pass exactly one of offer_id or talent_pool_id', which the schema does NOT encode (only candidate_id is marked required). That is real semantic value beyond 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+resource (put an existing candidate on a job/talent pool) and adds scope ('creates a placement in the pipeline's first stage') that clearly separates it from the move_candidate_stage sibling. An agent can pick this over create_candidate or move_candidate_stage just from the text.

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 usable context: it operates on an EXISTING candidate, and the caller must pass exactly one of offer_id or talent_pool_id. It does not explicitly name alternatives or state when-not conditions (e.g., versus move_candidate_stage), 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?

Annotations only supply destructiveHint=true, so the description carries most of the behavioral burden. It usefully discloses a real side-effect (no auto-confirmation email is sent) and the default-stage assignment behavior, but omits auth requirements, duplicate-handling, and response behavior.

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

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

Two tight sentences with the operation type front-loaded ('WRITE:'), then the manual-add semantics and assignment option. No filler; 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?

With no output schema and full schema coverage, the description adequately frames a create tool: purpose, write nature, email behavior, and optional assignment. It stops short of covering edge cases such as duplicate detection, validation failures, or permission requirements.

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 all 9 parameters. The description only marginally adds to parameter meaning by clarifying that job assignment is optional and lands in the job's default stage, which the offer_ids schema field already 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+resource ('add a candidate manually') with scope qualifiers (manual addition, optional job assignment). The 'WRITE' prefix and the POST endpoint make the operation unambiguous and easily distinguished from siblings like update_candidate or 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?

Implies usage via 'manually (as if a recruiter added them in the app — no auto-confirmation email is sent)', which hints at when this path is appropriate versus an invite/email-driven flow. However, it names no alternative sibling tools and states no explicit when-not-to-use 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?

Annotations only declare destructiveHint=true with no readOnlyHint, and the description's 'WRITE:' prefix is consistent with that, so there is no contradiction. However, it does not disclose what the create operation returns, whether it is reversible, or what permissions are required, so it adds modest context beyond the annotations rather than rich 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?

A single front-loaded sentence leads with the WRITE classification, then packs scope, the id-source hint, and the API endpoint with zero 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 six-parameter write tool with full schema coverage and no output schema, the description covers purpose, optionality of fields, and the dependency for admin_ids adequately. The only gap is that an agent gets no hint about what the created task response contains, which is minor given the absence of an output 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 all six parameters including the timezone requirement for due_date. The description adds one useful semantic link (admin_ids originate from recruitee_list_team_members) but otherwise restates what the schema covers, 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?

The description names a specific verb (create) and resource (recruiting task) and enumerates the key scope dimensions: optional candidate linkage, team-member assignment, and optional due date. It also explicitly tags the operation as a WRITE, so an agent can immediately tell it apart from read siblings like recruitee_list_tasks.

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 tells the agent where assignee ids come from (recruitee_list_team_members), which is a genuine routing hint toward a sibling tool. It does not state any when-not conditions or prerequisites beyond that, but the context given is clear and actionable.

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 carries the rest and does so: it discloses the exact response shape (one placement per job, each with placement id and current stage) and the underlying REST endpoint. It says nothing about auth requirements, rate limits, or behavior when the candidate id 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?

Three compact sentences with zero filler: the payload contents come first, the downstream dependency second, and the raw endpoint last. Every sentence earns its place 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?

With no output schema, the description must explain the return value and does: it lists the profile fields and clarifies the nested placements structure and why the placement id matters. Nothing an agent needs to call this read-only fetch 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?

Only one parameter and schema description coverage is 100% ('The candidate id.'), so the schema already carries the semantics. The description adds no format, range, or sourcing detail beyond the baseline, which is correct at 3 when the schema does the heavy lifting.

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') and enumerates the returned data: contact details, sources, tags, cover letter, CV URL, custom fields, ratings, and placements. The singular scope implicitly separates it from list_candidates and search_candidates, though it never names those siblings outright.

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 reason this tool is needed: the placement id it returns is the input recruitee_move_candidate_stage requires, which effectively documents a call-chain. It does not, however, state when to prefer this over list_candidates/search_candidates for retrieving candidate data.

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 covers the safety profile, so the bar is lower, and the description still adds real context: it discloses the endpoint (GET /c/{company_id}/admin) and flags the call as 'cheap', which is a genuine cost/behavioral signal. It stops short of detailing error behavior for invalid tokens.

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, front-loaded with what is fetched and followed by why to use it. The endpoint reference is a compact, useful appendix 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?

There is no output schema, so the description's enumeration of returned fields (name, email, role, role abilities, company id) is exactly the missing information an agent needs. Combined with the annotations, nothing required to call this zero-parameter tool correctly 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?

The tool takes zero parameters, so the baseline is 4 by rule. The description adds no parameter detail, but none is needed, and it usefully notes the company_id is implied by the token rather than passed.

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 a precisely scoped resource (the user the API token belongs to), then enumerates the returned fields (name, email, role, role abilities, company id). No sibling tool does anything comparable, so an agent can distinguish it 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?

Explicitly frames the use case — 'a cheap way to confirm the token and company id are right' — which tells the agent when to reach for it over other lookups. It does not name an alternative or exclusion, so it falls short of a full when/when-not statement.

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 goes beyond that by disclosing exactly what data is returned (description, requirements, salary, counters, pipeline_template_id), which is valuable since no output schema exists; it stops short of permission or error 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?

Front-loaded with the action and resource, and the field list and raw endpoint are compact. The 'Recruitee: GET /c/{company_id}/offers/{id}' clause is marginal value for an agent but does not bloat the text.

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, single-param tool with no output schema, the description compensates by enumerating returned fields and synonyms for the resource. Nothing essential for invocation is missing, though error/not-found handling is unmentioned.

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 fully documented in the schema, so the schema carries the load. The description only adds the loose synonym 'id' for offer_id, 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?

Specific verb ('Fetch one job or talent pool by id') plus the exact resource, and the singular scope clearly separates it from recruitee_list_offers. It even enumerates the fields returned, so an agent knows precisely what it gets.

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 'one ... by id' phrasing implies the fetch-a-single-record use case, but there is no explicit when-to-use or when-to-prefer-list_offers guidance, and no prerequisites or error conditions are stated.

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 by disclosing the ordered stage structure and field set returned, plus the integration linkage to other tools. It does not mention auth or pagination, but for a read-only lookup it adds meaningful context beyond annotations.

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 purpose and return shape, followed by the workflow linkage and the raw API endpoint. Zero filler; each sentence carries distinct, useful 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 compensates by disclosing the returned fields and ordering, and it places the tool within the broader candidate-stage workflow. Nothing an agent needs to call it correctly appears to be 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%, giving a baseline of 3, but the description goes further by explaining the provenance of pipeline_template_id (sourced from list_offers / get_offer), which the schema itself does not convey. That added meaning lifts it above the 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+resource ('Fetch a pipeline template') and enumerates the returned structure ('ordered stages (id, name, group, category)'). It further distinguishes itself from siblings by tying the resource to list_offers/get_offer and move_candidate_stage, so an agent knows exactly what it retrieves and why.

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: a job's pipeline_template_id names its pipeline, and the stage ids here are the inputs move_candidate_stage expects. This implicitly routes the agent to call it before stage moves, though it stops short of explicit when-not/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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the returned content (replies, author admin_id, visibility), which is important since there is no output schema.

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 purpose and followed by the endpoint mapping. Every clause carries information 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 single-parameter read tool with no output schema, the description supplies the essentials: what is listed and what fields come back. Only the usage context is thin, which keeps it just short of 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% for the single candidate_id parameter, which the schema already documents. The description adds no syntax, format, or meaning beyond what the schema provides, so the baseline of 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 (list) and resource (notes on a candidate's profile) and even names the underlying endpoint GET /c/{company_id}/candidates/{candidate_id}/notes. This clearly separates it from the write sibling recruitee_add_candidate_note, though it does not explicitly name any sibling.

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 the tool returns but offers no when-to-use guidance, no prerequisites, and no alternatives (e.g., get_candidate for broader profile data). Usage is only implied by the tool name.

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 already declaring a safe read, the description still adds real value: default ordering ('newest first'), the pagination arithmetic ('next offset = offset + limit'), and the underlying Recruitee endpoint. It does not disclose what the response payload contains or whether a total count is returned, 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?

Two sentences, no filler: the primary behavior and default ordering come first, filters second, and the pagination/endpoint details last. 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 read-only list tool with no output schema and 9 fully-described parameters, the description covers ordering, filtering, and pagination adequately. It leaves return-shape expectations and the alternate sort mode unaddressed, which are minor but real gaps.

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 beyond the schema by explaining pagination behavior (how to compute the next offset) and mapping the filter flags to intent. It omits any explanation of the 'sort' enum values (by_last_message), so it is not fully additive.

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 ('List candidates') and enumerates the filter dimensions (job, search, qualified/disqualified, ids, created_after), so an agent can grasp the scope immediately. It stops short of differentiating itself from the sibling recruitee_search_candidates, leaving that boundary implicit.

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 list of narrowing options implies when the tool is useful (broad enumeration with optional filters), but there is no explicit when-to-use guidance, no exclusions, and no pointer to recruitee_search_candidates or recruitee_get_candidate as alternatives. Usage is inferable rather than stated.

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 the underlying endpoint (GET /c/{company_id}/departments) and the shape of what comes back (ids and job counts), which is modest extra context but no pagination, auth, or scoping details.

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 that are front-loaded with the purpose and return content. 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?

With no output schema, the description carries the return-value burden and does name the key fields (ids and job counts). It is nearly complete for a simple zero-parameter list, though it omits pagination and any note on the implicit company_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?

The tool takes zero parameters, so there are no parameter semantics to document; baseline for a no-param tool is 4. The description does not need to compensate for any schema gaps.

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 (company's departments) and even names the returned fields (ids and job counts). The resource is plainly distinct from the candidate/offer/task-focused siblings, though the description does not explicitly contrast itself with any of 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?

There is no guidance on when to use this versus alternatives such as list_team_members or list_pipeline_template, and no prerequisites or exclusions are stated. Usage is only implied by the resource name.

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. The description adds that the reasons are company-configured and names the underlying endpoint (GET /c/{company_id}/disqualify_reasons), which is mild extra context but discloses nothing about pagination, ordering, or auth beyond what annotations imply.

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 purpose before the use case and endpoint. The middle sentence ('Useful for reading why candidates were disqualified') partially restates the first, so it is efficient but not maximally 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?

With no output schema, the description usefully names the returned fields (id, name, position), which compensates well. For a zero-param read-only list tool this is nearly complete; only ordering/pagination behavior is 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?

The tool takes zero parameters, so the schema carries no semantic burden; baseline is 4. The description helpfully clarifies that the result set is the company's preconfigured reasons, which is the only 'parameter-like' scoping information relevant here.

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 enumerates the returned fields (id, name, position). No sibling tool covers disqualification reasons, so it is unambiguously distinguishable from the other list_* 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?

Says it is 'useful for reading why candidates were disqualified,' which implies a use case but gives no explicit when-to-use vs. alternatives or any prerequisites. Adequate but leaves routing 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?

readOnlyHint=true already signals a safe read, and the description adds valuable return-content detail — that results come back as evaluations with rating+note and as questionnaire scorecards — which matters because there is no output schema. It does not discuss pagination behavior despite exposing page/limit.

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 tight sentence that front-loads the verb and resource before the optional filters, with no filler. Nothing restates the tool name or wastes tokens.

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 fully documented parameters, the description covers the main ambiguity — what data is returned — since there is no output schema. Only minor gaps remain (pagination interplay between page and limit, ordering of results).

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 loosely maps the 'kind' concept to its two result types and 'selected reviewers' to admin_ids, adding slight meaning but no syntax, defaults beyond what the schema already gives.

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+resource ('List interview results') with the two result types enumerated (evaluations with rating+note, questionnaire scorecards) and the filtering scope stated. No sibling tool covers interview evaluations, and the API endpoint anchors the meaning 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?

Conveys the optional filters ('for one candidate or by selected reviewers') so the agent knows when to narrow the call, but gives no explicit when-to-use/when-not guidance or alternative tools. Usage is implied by the filter phrasing rather than stated.

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 covers the safety profile, so the bar is lower; the description nonetheless adds valuable behavior by disclosing the default filter (upcoming, whole company) that would otherwise be invisible. It stops short of describing pagination behavior, though the schema documents page/limit.

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 compact clauses, front-loaded with the resource and returned fields, followed by default behavior and narrowing options, then the endpoint. Every sentence earns its place with zero 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, fully-schematized list tool with no output schema, the description covers purpose, return fields, default scoping, narrowing axes, and the underlying endpoint. 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%, so every parameter is already documented in the input schema. The description restates the narrowing dimensions (candidate, date range, interviewer) and returned fields but adds no syntax or format detail beyond the schema, so the baseline of 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 (List) and resource (scheduled interview events), and enumerates the returned fields (candidate_id, offer_id, stage_id, start time, duration, location, attendees). It is the only interview-events tool among the siblings, so the resource 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?

Clearly states the default scope ('upcoming events for the whole company') and the narrowing axes ('by candidate, date range or interviewer'). No sibling alternative is named, but none of the listed siblings overlaps with interview events, so no explicit exclusion is required.

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 adds real operational context beyond that: default page size of 1000, pagination mechanics, and that meta.total_count carries the total. It stops short of rate-limit or auth details.

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 compact sentences, front-loaded with the resource and returned fields, then filters, then pagination and endpoint. No filler or repetition of 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 14-param read-only list tool with no output schema, the description compensates by naming the returned field set and the meta.total_count envelope, and covers filtering and pagination. Nothing critical for 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 baseline is 3, but the description genuinely enriches semantics by labelling `include` values as 'heavy fields' with examples (counters, description, salary, location_ids) and by flagging defaults for limit/page.

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 (company's jobs), explicitly reconciles Recruitee's 'offers' terminology, and enumerates the fields returned. This clearly separates it from siblings like get_offer (single job) and list_candidates.

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 how to use it: filter by status/department/location/recruiter/hiring manager/tag, add heavy fields via `include`, and paginate with limit+page. It does not explicitly contrast with get_offer or list_candidates, but the listing 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?

Annotations already declare readOnlyHint=true, so safety is covered; the description adds useful behavior detail by naming the return contents (ids and usage counts) and the underlying GET endpoint. Minor gaps remain (pagination, whether counts are live), but it adds real value beyond the structured fields.

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, zero filler: purpose, downstream utility, and endpoint. The most decision-relevant information (what it lists, what the ids are for) is front-loaded.

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 compensates by stating the return shape (ids and usage counts) and the cross-tool linkage to candidate search. Nothing essential for correct invocation is missing for a 3-parameter, all-optional 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% and both enums are documented in the schema, so the schema carries parameter meaning. The description adds nothing about query/sort_by/sort_order semantics, 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?

Specific verb+resource ('List the company's candidate tags') plus a disclosure of what is returned (ids and usage counts). It also distinguishes itself from tag-mutating siblings like recruitee_add_candidate_tags by framing it as a read of company-wide tags.

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 connects the output to a downstream use case — tag ids feed recruitee_search_candidates filters — which tells the agent why and when to call it. It lacks an explicit 'don't use this for X' exclusion, but the routing 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?

Annotations only declare readOnlyHint=true, so the description carries the rest. It usefully discloses that the endpoint and the set of applicable parameters change depending on whether candidate_id is present — material behavior beyond what annotations state. It does not describe pagination or return envelope behavior, 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 dense sentences with the core capability and the mode split front-loaded. The inline REST paths add disambiguation value but are slightly heavy for a listing tool, keeping it just under a 5.

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 8 optional params and no output schema, the description compensates by naming the returned fields and by clarifying which params are inert in candidate mode. What remains thin is sorting/paging behavior and any indication of result size limits.

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's description already carries the '(company list only)' qualifier, so baseline is 3. The description consolidates the same information ('only `status` applies') but adds no syntax, default, or format detail beyond 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 ('List recruiting tasks') and enumerates the fields returned (title, description, due date, completed, candidate_id). It also splits the operation into two clearly named modes, which separates it from siblings like recruitee_create_task.

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 conditional routing: when candidate_id is supplied, only `status` applies; otherwise the company-level scope/assignee/sorting/paging parameters apply. It stops short of naming an alternative sibling tool for a given situation, but the mode selection 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable return context that annotations do not provide: the membership fields (admin_id, role, recruiter/hiring-manager status, accessible jobs) and the location of user names/emails in the references array.

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 then layers in output fields, cross-tool usage, and endpoint detail. Every sentence contributes, though four sentences make it slightly denser than the most concise high-scoring examples.

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 does meaningful work by listing the return fields and explaining the references array. It does not cover pagination or response envelope details, but those are partly handled by the schema's page/limit parameters, so it is largely complete for a 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 the schema already documents all six parameters fully. The description does not add parameter-specific syntax, format, or usage guidance beyond what the schema provides, which is the baseline for high coverage.

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 ('List the company's team members (memberships)') and enumerates the key fields returned. It does not explicitly differentiate this tool from sibling list 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?

The description implies usage by saying 'Use admin_id values for task assignees and filters,' which helps an agent know why to call it. However, it gives no explicit when-to-use guidance, no exclusions, and no named alternatives among the many sibling list and user 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?

Annotations only flag destructiveHint=true; the description adds genuine behavioral context beyond that — stage automations configured in Recruitee may fire as a side effect, the hired-stage extra requirement, and the undo path. 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?

One dense, front-loaded block: write marker, action, id provenance, conditional requirement, side effects, undo, endpoint. No filler sentences.

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 three-parameter mutation tool with no output schema, the description covers action, prerequisites, data sources, side effects, and reversibility. An agent has 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%, so the baseline is 3; the description earns above that by disambiguating placement_id vs candidate_id and stating the conditional requirement for work_location_id, which the schema only implies.

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 (move) and resource (candidate → stage of a job's pipeline) and opens with a WRITE marker. The 'placement id, not candidate id' scoping makes it clearly distinguishable from siblings like 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?

Explicitly tells the agent where each id comes from (recruitee_get_candidate → placements[].id, and recruitee_get_pipeline_template for the stage), when work_location_id is required (hired stage), and how to reverse the action (move back).

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 covers the safety profile, so the bar is lower; the description still adds real value by disclosing the return shape (`hits` with placements and stage, plus `total`) and the fact that it is a pass-through to the underlying GET /search/new/candidates engine. It stops short of 5 because pagination behavior and hit caps are only implied via the schema.

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 purpose, then progressively more specific detail (query semantics, filter examples, return shape, raw endpoint). No filler sentences, though the trailing API endpoint reference is of marginal value to an agent and the filter examples make the block dense.

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 the return contract — and it does, naming `hits`, nested placements (job + current stage), and `total`. Combined with the filter syntax guidance, 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 coverage is already 100%, yet the description goes well beyond it: it enumerates which fields `query` actually searches (name, emails, phones, tags, sources, job assignments, stage, cover letter, CV), and gives four concrete `filters` shapes including the Unix-seconds convention for created_at and the two filter-object variants (field/eq vs filter/id.in). This is exactly the kind of syntax detail the schema's `additionalProperties: {}` leaves open.

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 ('Search the company's candidates') and clarifies it uses Recruitee's native search engine. It does not explicitly differentiate itself from the sibling recruitee_list_candidates, which an agent could plausibly pick instead, 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?

Usage is implied by the presence of `query` and `filters` (use this for filtered/free-text search), but there is no explicit when-to-use or when-not-to-use statement, and the obvious alternative (recruitee_list_candidates) is never named or excluded.

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 carry destructiveHint=true, so the description carries real weight: it discloses PATCH semantics, that only passed fields change, and critically that list fields (emails, phones, links, social_links) REPLACE rather than append. That replacement warning is exactly the behavior an agent would otherwise get wrong and is not present in the schema or annotations.

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 tightly packed sentences, front-loaded with the WRITE marker and the operation, followed by the partial-update rule and the replacement hazard, ending with the API path. 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 7-parameter mutation with no output schema, the description covers the operation, mutation semantics and the list-replacement trap. It could still note whether fields can be cleared or whether cover_letter is controllable, but nothing essential for a correct call 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 the baseline is 3, but the description adds meaning beyond it by clarifying partial-update semantics ('only the fields you pass change') and the full-replacement contract for list parameters, which the schema's per-field descriptions do not 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 ('WRITE: update a candidate') and even names the fields affected, which separates it from create_candidate and add_candidate_tags. Minor imprecision: it scopes the update to 'name or contact details' while the schema also exposes cover_letter, so the stated scope is narrower than the tool's actual capability.

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 when-to-use guidance and no routing to alternatives (e.g. use add_candidate_tags for tags, or create_candidate for new records). The only disambiguation is implicit in the verb 'update', leaving the agent to infer selection 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.