Taleez MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: no message is sent to candidates and the write is a pure association on the job's pipeline, plus the POST endpoint. It does not say what happens when a candidate is already in the pipeline or when some ids in the batch are invalid.

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 'WRITE:' and packed into one dense sentence-plus-parentheticals with no filler. The nested asides make it slightly harder to scan than a clean two-sentence structure, 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 3-parameter mutation with no output schema, the description covers what it does, its non-obvious semantics and its location nuance. The remaining gap is outcome behavior, i.e. batch partial-failure handling and whether already-associated candidates are silently ignored (implied only by idempotentHint).

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 all three parameters are documented in-schema, so the baseline is 3. The description's only parameter content, the location_id rule, restates the schema's 'only for a job with several locations' almost verbatim, adding no new syntax or format detail.

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 ('associate existing candidates to a job') plus the effect ('appear in its recruitment pipeline'), and preempts the most likely confusion by saying this is a recruiter association, not a candidate application. An agent can distinguish it from taleez_create_candidate and the pool variant without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete conditional instruction ('Pass location_id for a job with several locations') and clarifies the semantics of the operation (recruiter association, no message sent), which tells the agent when this is the right call versus its siblings. It never names taleez_add_candidates_to_pool explicitly as the alternative, so the job-vs-pool routing is left to inference.

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

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

Beyond the annotations (which already state readOnly=false, idempotent=true, destructive=false), the description adds two real behavioral facts: duplicates are harmless and no message is sent. That extra context matters for a write tool, though nothing is said about permissions or what happens if a candidate id is invalid.

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

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

Three short, front-loaded sentences: an operation marker, two behavioral notes, and the endpoint. Every clause adds information and nothing is repeated from the name or annotations.

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 write tool with no output schema, the description covers the operation, duplicate semantics, notification behavior, and endpoint. It doesn't address error conditions or partial failures when a subset of candidate_ids is invalid, which keeps it short of complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns a bit more by telling the agent where pool_id comes from (taleez_list_pools) and constraining candidates to "existing" records. It still doesn't say how candidate_ids should be sourced or what the 100-item cap behavior is, so it isn't a full 5.

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

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

The description opens with a specific verb and resource ("add existing candidates to a talent pool") and the word "existing" plus "pool" cleanly separates it from taleez_create_candidate and taleez_add_candidates_to_job. An agent can identify the operation without consulting any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly names taleez_list_pools as the way to obtain the pool id, giving the agent a concrete prerequisite path. It lacks an explicit when-not or a direct contrast with taleez_add_candidates_to_job, but the pool-vs-job distinction is implied by the resource wording.

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 destructiveHint=true and idempotentHint=false, but the description adds the concrete consequence an agent needs: calling twice without a mail produces two duplicate candidates, and no notification e-mail is dispatched. The unique-mail constraint and the POST endpoint are extra operational context; only the response shape is left unexplained.

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

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

Four tight sentences led by a 'WRITE:' marker, with the required-field and uniqueness constraints front-loaded before the non-idempotency warning. No sentence is filler; each adds a distinct fact.

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 10-parameter mutation with nested objects and no output schema, the description covers the highest-risk behaviors (duplicates, no e-mail, no job link). It never says what the call returns (presumably the created candidate and its id), which is the one thing an agent cannot infer from a missing 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 coverage is 80%, so most parameters are already documented; the description reinforces the required first/last name and the company-wide uniqueness of mail, both of which the schema already states. It adds no guidance on the nested location object, lang default, or unit_id/recruiter_id usage, so baseline 3 is right.

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?

Names a specific verb and resource ('add a new candidate to the Taleez database') and immediately scopes it against siblings by stating the record is created without a job attachment, which separates it from taleez_add_candidates_to_job and taleez_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?

The 'Creates a record only: the candidate is not attached to a job and no e-mail is sent by this call' clause tells the agent when this tool is insufficient and points implicitly at the add-to-job flow. It does not explicitly name the alternative tool or state prerequisites such as account permissions, so it falls short of a full when/when-not routing 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the underlying endpoint (GET /0/candidates/{id}) and the shape of the returned payload, which is useful, but it says nothing about behavior for unknown ids (404 vs empty) or permission 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?

Two short fragments, zero filler, and the identifying clause ('One candidate by id') is front-loaded ahead of the field list and endpoint. Every element 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?

No output schema exists, so the description compensates well by listing the fields returned and citing the REST endpoint. For a simple one-parameter read, the only real gap is unspecified error/not-found behavior.

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

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

With a single parameter at 100% schema description coverage ('Taleez candidate id.'), the schema already carries the semantics. The description's 'by id' adds nothing beyond confirming 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 and resource ('One candidate by id') and enumerates the fields returned (name, mail, phone, language, location, social links, unit, CV link, custom properties). The singular 'one candidate by id' cleanly separates it from the sibling list_candidates and the update/create variants.

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: an agent infers it should call this when it already has a candidate_id. There is no explicit statement of when to prefer this over taleez_list_candidates, taleez_get_candidate_properties, or the other get_candidate_* siblings that also take a candidate id.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds that the response enumerates association types and history, plus the underlying endpoint GET /0/candidates/{id}/applications, but says nothing about pagination, volume or ordering of the returned applications.

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 that front-loads the purpose and then lists the returned fields, plus the endpoint reference. Nothing is redundant, though the parenthetical enumeration of association types is slightly heavy.

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 explaining the return shape, and it does so by naming the key fields (type, job id, step, dates, history). Only pagination/limit behavior is left unaddressed, which for a per-candidate list 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% for the single candidate_id parameter, so the schema already carries its meaning; the description only echoes the path template. Baseline 3 applies since no additional parameter semantics are provided.

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 resource (a candidate's applications/associations) and enumerates what it returns: association types such as SPONTANEOUS/APPLICATION_TO_A_JOB, job id, current pipeline step, rejected/hired dates and step history. That clearly separates it from siblings like taleez_get_candidate or taleez_get_candidate_events, though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The framing 'Where a candidate stands' implies the use case (tracking a candidate's pipeline position across jobs), but there is no explicit when-to-use versus when to pick taleez_get_candidate, taleez_add_candidates_to_job or taleez_get_candidate_pools, and no stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value by disclosing the shape of the payload (id, name, date, size, file URL), which matters because there is no output schema. It stops short of noting auth requirements, pagination, or whether file URLs expire.

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 listing the resource and its fields, followed by the endpoint. Nothing is padded, though the raw endpoint string is of marginal use to an agent compared to the field list.

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 tool with no output schema, the description supplies the essential missing piece — the returned fields — and the annotations cover safety. Only minor gaps remain (empty-result behavior, URL lifetime, whether documents include non-CV attachments).

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?

Single parameter candidate_id with 100% schema description coverage ('Taleez candidate id.'), so the schema does the documentation work. The endpoint path '{id}/documents' reinforces that the id is the candidate, but the description adds no new semantics such as where to obtain the id or error behavior for unknown ids.

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?

Names the exact resource (documents attached to a candidate) and enumerates the returned fields (id, name, date, size, file URL), plus the underlying endpoint. The resource is distinct enough from siblings like taleez_get_candidate and taleez_get_candidate_applications that an agent can tell them apart, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as taleez_get_candidate_applications when the agent actually wants applications rather than files. Usage must be inferred entirely from the tool name and resource noun.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the concrete shape of the returned records, which matters because no output schema exists, but it says nothing about pagination, date-range behavior, or whether the list can be empty.

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, front-loaded with the resource and followed by the returned fields. The trailing 'GET /0/candidates/{id}/events' is mild redundancy but confirms the scope cheaply.

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 annotations covering safety, the description's enumeration of returned fields largely carries the burden left by the absent output schema. Only pagination and empty-result behavior are missing, which are minor for this shape.

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 candidate_id parameter is already documented as 'Taleez candidate id.' The description adds no format, range, or sourcing guidance beyond what the schema provides, so baseline 3 applies.

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

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

States a specific resource (events for a candidate) and enumerates the returned data: subject, start/end, location, meeting URL, attendees. It is clear enough to distinguish from taleez_get_candidate, but it never explicitly contrasts with the sibling taleez_list_events, which appears to serve the same domain with a different scope.

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 it fetches but not when to choose it over taleez_list_events or the other candidate sub-resources. There are no stated prerequisites, scope notes, or exclusions, so an agent must infer from the names alone that this is the candidate-scoped variant.

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, destructiveHint=false and openWorldHint=true, covering the safety profile. The description adds the return shape (pool id, name, date added, referrer) and the underlying endpoint, which is useful, but says nothing about pagination or empty-result behavior for a candidate with no pools.

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 segments with the returned fields front-loaded and the endpoint appended as a reference. No waste, though the leading fragment lacks a verb and relies on the reader completing the sentence from the 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?

For a simple single-parameter read with no output schema, the description compensates by naming the returned fields, which is the main thing missing from structured data. Annotations handle safety; only pagination/empty-state 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?

There is only one parameter and schema description coverage is 100%, so the schema fully documents candidate_id as a Taleez candidate id. The description only echoes it via the {id} path template and adds no format or constraint detail 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?

Names the resource precisely (talent pools a candidate belongs to) and enumerates the returned fields, so an agent knows exactly what to expect. It does not differentiate from the reverse-direction sibling taleez_list_pool_candidates or mention the underlying GET endpoint's resource direction explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the required candidate id and the 'belongs to' phrasing, making it clear this is the candidate→pools direction. There is no explicit when-to-use versus taleez_list_pool_candidates or taleez_add_candidates_to_pool, so the agent must infer the direction from the 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value by naming the return fields and the underlying endpoint, but says nothing about behavior when the candidate has no custom properties, an unknown id, or whether values are typed differently per choice vs free-text.

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 clause describing the payload plus the endpoint path, front-loaded with the resource and its returned fields. No filler, though the raw endpoint reference adds little for an agent that won't call HTTP directly.

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 annotations covering the safety profile, describing the returned field set is essentially the remaining burden, and it does that. Minor gaps (empty-property case, error behavior) are acceptable 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?

Only one parameter exists and the schema documents it at 100% coverage ('Taleez candidate id.'). The description adds no further meaning about id semantics or scope, so this sits at the baseline where the schema does the work.

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

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

States a specific verb+resource: returns the custom property values of one candidate, and even enumerates the returned fields (property id, name key, type, value or choices). This distinguishes it implicitly from list_candidate_properties and set_candidate_properties, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No statement of when to use this versus taleez_list_candidate_properties (property definitions) or taleez_get_candidate (full candidate record). The agent must infer from the name which of the several candidate-scoped getters to pick.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered for the agent. The description adds the concrete endpoint (GET /0/jobs/{id}) and the breadth of returned data, but says nothing about behavior on a nonexistent or unauthorized id, nor about field visibility/permissions.

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

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

One front-loaded sentence carrying the returned-field inventory, followed by the endpoint mapping. No filler, no restatement of the 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 compensates by naming the payload contents an agent will receive, which is the key gap for a get-by-id tool. With only one required parameter and full annotation coverage, nothing material is missing 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?

There is a single parameter with 100% schema description coverage ('Taleez job id.', integer, exclusiveMinimum 0), so the schema does the work. The description only restates 'by id' and adds no format, source, or acquisition guidance (e.g., from taleez_list_jobs).

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 ('One job posting by id') and enumerates exactly what comes back: descriptions, contract, location, recruiter, unit, tags, custom properties, URLs. That enumeration plus the 'by id' framing makes it distinguishable from taleez_list_jobs and from the sub-resource getters like taleez_get_job_steps.

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 rather than stated: 'by id' signals this is the single-record companion to taleez_list_jobs, and the field list hints that related data such as questions, steps, and statuses must be fetched via their own siblings. No explicit when-to-use/when-not or named alternative is given.

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 readOnly, non-destructive and open-world, so the safety profile is covered. The description adds a genuine behavioral detail beyond the annotations: only filter values with at least one job are returned, which affects how an agent should interpret the results (no zero-count buckets). No further caveats such as caching or freshness are given, keeping it at a 4.

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: return shape first, use case second, endpoint last. No filler, and the most important information (what comes back) 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?

There is no output schema, so the description must carry the return contract, and it does by enumerating the breakdown dimensions and the zero-count omission rule. What is missing is any hint about the shape of individual counts (e.g. key/count pairs) or ordering, which would help an agent parse the response.

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; baseline 4 applies. The schema is trivially complete (empty properties object).

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 precisely what is returned: total job count plus counts broken down by status, contract, city, tag and company label. It clearly distinguishes this aggregate view from listing tools like taleez_list_jobs. It loses a point because the leading sentence is a noun phrase rather than a verb, so the 'count' action is only inferable from the title and the endpoint.

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?

'A quick overview of the hiring activity' implies the use case (aggregate snapshot rather than detailed retrieval), but no explicit when-to-use/when-not or named alternative is given. An agent must infer that list_jobs is the sibling to pick when individual job records are needed.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond that by listing the shape of each returned question (id, label, type, required, choices) and citing the underlying endpoint, which is meaningful 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?

One compact sentence plus a path reference – the resource description is front-loaded and nothing is padded. The trailing 'GET /0/jobs/{id}/questions' is slightly redundant with the tool name but does supply the API mapping an agent may need.

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 tool with full annotation coverage and no output schema, the description supplies the field list that would otherwise be missing. Minor gaps remain around ordering, whether questions can be empty, and any pagination, but nothing blocks 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?

There is a single parameter (job_id) and schema coverage is 100%, so the schema already documents it as 'Taleez job id.' The description reinforces the scoping ('applying to a job' and the {id} path segment) but adds no format, sourcing, or validity detail 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?

The description names a specific resource – the questions candidates answer when applying to a given job – and enumerates the returned fields (id, label, type, required, choices), which separates it from siblings like taleez_get_job_filters or taleez_get_job_steps. The verb is only implied via the endpoint string rather than stated outright, so it falls short of a perfect 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 purpose statement: an agent that needs the application form questions for a job will recognize this tool. However, there is no explicit 'use this when' framing and no comparison against related siblings such as taleez_get_job_filters or taleez_get_job_steps, so the agent must 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the returned status vocabulary and the REST endpoint, but says nothing about ordering (ascending/descending), pagination, or whether the list is complete — modest added value over the 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?

Two compact fragments with the returned content front-loaded and no filler. The trailing endpoint string is slightly redundant but confirms the exact REST call, so almost 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-shape burden and does so reasonably: it names the per-change fields and the status enum. It falls short only on ordering and pagination behavior, which an agent would need to interpret a long history.

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 job_id parameter is documented as 'Taleez job id.' with a positivity constraint. The description only restates it as {id} in the path, adding no new semantics, 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 the specific resource (status history of a job) and enumerates the returned content (date timestamp plus status values DRAFT/PUBLISHED/SUSPENDED/DONE), which clearly separates it from siblings like taleez_get_job or taleez_get_job_steps. It is a noun phrase rather than a verb+resource statement, but the intent 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?

There is no explicit 'use this when' guidance or mention of alternatives such as taleez_get_job for current state. Usage is only implied by the returned content and the endpoint path, leaving the agent to infer when history is preferable to a plain job fetch.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results come back ordered, which matters for interpreting position, but says nothing about pagination, behavior when a job has no steps, or error handling.

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 returned and followed by the practical use. The trailing raw endpoint path is minor noise but does not obscure anything.

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, read-only, single-parameter tool with full schema coverage and no output schema, the description does what is needed: it states the returned shape and the reason to call it. Only the absence of edge-case behavior (empty pipeline, invalid job id) 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% for the single job_id parameter, so the schema already documents the input. The description adds no format, sourcing, or scoping detail beyond that, 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?

The description names a specific verb and resource ('recruitment pipeline steps of a job, in order') and enumerates the returned fields (id, name, order). It implicitly separates itself from siblings like get_job_statuses or get_job_filters by scoping to a job's pipeline, though it never names those alternatives explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It offers one concrete use case ('read where each candidate stands'), which gives an agent a workable sense of when to call it. However, there is no exclusion guidance, no mention of how it relates to get_job or get_candidate_applications, and no prerequisites 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 this a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description adds the returned field set and the underlying endpoint, plus the fact that disabled properties may be relevant. Pagination mechanics are left entirely to 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?

Two short sentences plus a bare endpoint reference, with the resource and its fields front-loaded and nothing redundant. Every element earns its place.

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

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

With no output schema, listing the returned fields is exactly the right compensation, and parameter behavior is covered by a 100%-covered schema. The main residual gap is the missing distinction from taleez_get_candidate_properties, which an agent could easily confuse with this listing 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, page_size, and with_disabled are already fully documented, and the baseline of 3 applies. The description adds no extra meaning for them — the word 'disabled' in the returned-field list hints at the with_disabled flag but never explains the default exclusion behavior.

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 the resource precisely ('custom candidate properties defined in the account') and enumerates the returned fields (id, name, type, choices, disabled), which separates it from taleez_list_job_properties. The verb is implicit rather than stated ('list' only appears in the title), and it never contrasts with taleez_get_candidate_properties, the closest 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 forward reference 'Use the ids with taleez_set_candidate_properties' gives a concrete downstream use, which is real guidance. But there is no when-to-use vs when-not framing and no disambiguation from taleez_get_candidate_properties, so an agent must infer the split between the two.

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, openWorldHint, and destructiveHint=false. The description adds meaningful context beyond that: candidates contain personal data restricted to the user's own recruiting, custom properties are omitted unless with_props is set, and the returned fields are listed. Pagination behavior is left to 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?

The description is front-loaded and compact, with the field list and usage notes packed into a few lines. The endpoint suffix is mildly redundant but still contextual and not wasteful.

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 listing returned fields. It also covers privacy constraints and the with_props behavior. Pagination and page-size details are left entirely to the schema, which is acceptable given full schema coverage.

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 all four parameters are documented in the schema. The description still adds value by clarifying that e-mail filtering is exact and intended to find one person, and by reinforcing that custom properties require with_props.

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

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

The description clearly states a specific verb and resource ('List the candidates in the company') and enumerates the returned fields. It does not explicitly distinguish itself from sibling tools such as list_pool_candidates or get_candidate, though the company-wide scope is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives useful hints: filter by exact e-mail to find one person, and use with_props for custom properties. However, it does not explicitly say when to use this list tool versus get_candidate or the pool-specific list tools, leaving alternatives implicit.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful content by listing what the payload contains (subject, timestamps, location, meeting URL, job id, attendees), but says nothing about result volume, ordering defaults, or what an empty result looks like.

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 that front-loads the verb and resource, then the returned fields, then the endpoint. Nothing is redundant 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 read-only list tool with no output schema, listing the returned fields is exactly the right compensation, and annotations plus schema cover safety and paging. The remaining gap is disambiguation from taleez_get_candidate_events, which the description should have handled given how similar the sibling names are.

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%, with page, page_size, sort_by and sort_direction all documented in-schema (including pagination chaining via next_page). The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

Uses a specific verb (List) plus a clearly scoped resource (the company's calendar events) and enumerates the returned fields, so an agent knows exactly what it gets back. However, it never distinguishes itself from the sibling taleez_get_candidate_events, which reads as the same resource filtered differently.

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 statement of when to use this versus taleez_get_candidate_events or any other sibling, and no prerequisites or scoping advice. The only implicit signal is 'company's' versus the candidate-scoped sibling, which the agent must infer rather than read.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the scope is account-wide with no filtering and appends the HTTP route, but says nothing about result volume, pagination behavior, or whether default/system properties are included.

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 plus the endpoint path; zero filler, and the returned-field list is packed into the same clause rather than a separate sentence.

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 parenthetical field list (id, name, type, choices) usefully stands in for the response shape, and annotations cover the safety profile. Minor gap: it does not say whether the list includes system-defined properties or how large the collection typically is.

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 (page, page_size) are documented there, including the 'pass the previous reply's next_page' convention. The description contributes nothing about parameters, 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?

The description identifies a specific resource (custom job properties defined in the account) and enumerates the returned fields (id, name, type, choices), so an agent knows exactly what it fetches. It stops short of explicitly distinguishing itself from the similarly named taleez_list_candidate_properties, leaving that distinction to be inferred from 'job' vs '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 only implied: a paginated list of account-level property definitions with no filters. There is no explicit statement of when to call this versus taleez_list_candidate_properties or taleez_get_job_filters, and no prerequisites are mentioned.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful payload detail that long HTML descriptions are omitted unless with_details is set, which is beyond what the annotations say.

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 front-loaded sentences with no filler; the parenthetical field list is dense but genuinely informative. Minor trimming possible around the enum statuses already in the schema.

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

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

For a 13-parameter list tool with no output schema, the description compensates by enumerating the returned fields and explaining the with_details payload switch, which is the key thing an agent cannot infer from the 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 every parameter including enums and pagination. The description only summarizes the filter set and restates the with_details effect, adding little beyond structured data; 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 job postings of the company') and enumerates the returned fields, so an agent can tell this apart from the single-record taleez_get_job. It also pins the underlying endpoint GET /0/jobs.

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?

Names the supported filters and sort axes and flags that descriptions require with_details, giving clear context for when this is the right call. It stops short of explicit exclusions or pointing to taleez_get_job for single-record lookups.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the with_props behavioral nuance and the endpoint path, but says nothing about pagination behavior, result ordering, or what an empty pool returns.

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

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

Three short fragments, front-loaded with the core purpose and zero filler. It is telegraphic rather than wasteful, though the sentence fragments read more like notes than prose.

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 4 params, full schema coverage, and annotations in place, the definition is enough to invoke the tool correctly. However, with no output schema, the description leaves the response shape (candidate objects, next_page pagination) unexplained.

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

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

Schema description coverage is 100%, so all four params (page, pool_id, page_size, with_props) are fully documented in structured data. The one parameter note in the description ('Custom properties only with with_props') merely restates the schema's with_props description, adding no new meaning.

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 ('The candidates in one talent pool'), which clearly separates it from sibling taleez_list_candidates (all candidates) and taleez_list_pools (pool metadata). The sentence is a fragment and never says 'list' or 'returns', but the meaning 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?

No when-to-use/when-not guidance and no named alternative, despite siblings like taleez_list_candidates and taleez_get_candidate_pools that an agent could confuse it with. The only routing hint ('see taleez_list_pools') lives in the pool_id schema description, not the tool description.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete response fields and the underlying endpoint, but says nothing about pagination limits or rate behavior beyond what the schema 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 front-loaded sentence naming the resource, scope and returned fields, followed by the endpoint path. Nothing is padded, though the raw endpoint reference adds little for an agent.

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 paginated read tool with full annotation coverage, complete schema docs and named return fields, an agent has enough to call it correctly. Only the lack of routing guidance against sibling pool tools 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% and both parameters (page, page_size) are fully documented in the schema, including the 'pass the previous reply's next_page' guidance. The description adds nothing beyond that, 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 and resource ('List the talent pools') plus the scope ('of the company') and enumerates the fields returned (id, name, dates, recruiter). It is clearly distinct from siblings like taleez_list_pool_candidates or taleez_list_candidates, though it never explicitly says so.

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 indication of when to choose this over taleez_list_pool_candidates or taleez_get_candidate_pools, and no prerequisites or follow-up workflow are mentioned. Usage is only implied by the nature of a list endpoint.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds that results are scoped to 'the company' and that entries carry ids usable elsewhere, but says nothing about pagination behavior or ordering beyond what the schema already spells out.

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

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

Three short sentences with the purpose front-loaded and no filler. The trailing raw endpoint ('GET /0/recruiters') is marginally useful for debugging but adds little for an agent.

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 read-only list with no output schema, the description conveys scope, the entity returned (users with ids), and why those ids matter. A brief note on the returned shape would make it complete, but nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and both parameters (page, page_size) are fully documented there, including the next_page chaining hint. The description adds no parameter guidance, 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 and resource ('List the recruiters (users) of the company'), which no sibling tool duplicates — list_units, list_jobs, list_pools all target different resources. It doesn't explicitly contrast itself with a sibling, but the resource noun alone 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 second sentence explains downstream uses of the returned ids ('to read who owns a job or to credit a new candidate'), which implies when this lookup is needed, but it never states when to call this versus alternatives or any prerequisite. 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint and the fact that returned ids are consumed as job filters, which is genuine context. It does not disclose rate limits, whether the list is exhaustive per page, or return fields, so it's a modest add rather than rich behavioral detail.

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: what it lists, why the caller cares, and the endpoint. Front-loaded with the resource definition and zero filler. Nothing repeats 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 simple two-parameter read with full schema coverage and annotations carrying safety, this covers nearly everything needed to invoke correctly. The only soft gap is return shape — no output schema exists, so stating which fields a unit carries (beyond ids) would have closed the loop.

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 (page, page_size) are fully documented in the schema, including the next_page chaining hint, so the baseline is 3. The description contributes nothing about the parameters themselves — 'use the ids' refers to output, not inputs.

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

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

States a specific verb and resource and, crucially, disambiguates the ambiguous term 'units' as entities/subsidiaries/sites of the company. That tells an agent this is an org-structure lookup, clearly distinct from job/candidate/pool siblings. It stops just short of naming an alternative explicitly, but the parenthetical does the disambiguation work.

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 sentence 'Use the ids to filter jobs' implies a downstream workflow (fetch units, then scope jobs by unit id), which is useful implied guidance. However, there is no explicit statement of when to call this versus not, no prerequisites, and no note that pagination must be followed to enumerate all units.

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 destructiveHint=true, idempotentHint=true, readOnlyHint=false; the description adds real specifics beyond them, notably that listed properties are overwritten and that an empty choices list clears all selections unless append_choices is true. It doesn't mention auth requirements or partial-failure behavior, but the overwrite semantics are well disclosed.

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

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

Four tight sentences front-loaded with 'WRITE', followed by the branching rule, the clearing caveat, the overwrite warning, and the endpoint. No redundant restatement of the 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?

For a nested mutation tool with no output schema, the description covers the parameters, the clearing/append edge cases, and the overwrite effect, which is enough to invoke it correctly. Missing only surrounding operational context such as error handling or response shape, which is minor.

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

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

With 50% schema coverage, the description earns its keep: it specifies DATE format yyyy-MM-dd, the value-vs-choices split keyed on property type, and the empty-list/append_choices interaction, all of which add meaning beyond the nested schema descriptions. candidate_id semantics are 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 ('set custom property values') on a specific resource ('a candidate'), and prefixes 'WRITE' to immediately flag the operation class. Clearly distinguishable from the sibling read tool taleez_get_candidate_properties and from taleez_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?

Gives concrete conditional guidance: use 'value' for properties without choices, 'choices' for properties with choices, and routes the agent to taleez_list_candidate_properties to obtain choice ids. It stops short of explicitly contrasting with taleez_update_candidate, but the property-scoped 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?

Goes well beyond the annotations: it explains the read-then-rewrite mechanics (unchanged name/mail/phone are sent back because the endpoint otherwise requires first and last name), states that social_links and location REPLACE rather than merge and that an empty social_links object clears them, and clarifies that no notification is sent. The destructiveHint and idempotentHint annotations are confirmed and enriched with concrete consequences.

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 dense sentences with zero filler: operation marker first, then update semantics, then the destructive replacement caveat, then the endpoint. Every clause carries information an agent would otherwise have to guess.

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

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

For a destructive, nested-object, 7-parameter mutation, the description supplies the essential behavioral context (partial update, replacement semantics, no notification). It omits what the call returns and what happens for an unknown candidate_id, which matters slightly given there is no 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?

With 71% schema coverage, the schema already documents most fields; the description still adds real meaning by framing the whole call as a partial update (only what you pass changes) and by spelling out the destructive replacement semantics for the two nested object parameters. It does not add detail on first_name/last_name beyond the schema, which is a minor remaining gap.

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 'WRITE:' marker and names the exact resource and mutable field set ('name, e-mail, phone, social links or location'), which cleanly separates it from the read siblings (get_candidate, list_candidates) and from create_candidate. An agent can identify the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the field enumeration and the 'Overwrites data; no message is sent' warning, but there is no explicit when-to-use/when-not guidance and no reference to the closest alternative, taleez_set_candidate_properties, which an agent could easily confuse with this tool since both mutate a candidate.

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