Traffit MCP by usefulapi

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

Annotations only supply destructiveHint=true and a title, so the description carries most of the load — and it does, disclosing that the operation is additive and non-idempotent (each call appends a new note). It does not explain why the operation is flagged destructive or whether notes can be duplicated/removed, leaving one gap against the annotation.

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

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

Three tight, front-loaded clauses starting with 'WRITE:' so the operation type is immediately visible. The raw endpoint is mildly redundant but cheap, 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 two-parameter append tool with no output schema, the description covers the essentials: write semantics, non-idempotency, and authorization scope. Minor omissions (visibility of the note to other users, duplicate handling at the API level) are low-risk for correct invocation.

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

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

Schema coverage is 100% with both parameters documented (candidate_id as numeric id, content with length bounds), so the schema does the heavy lifting. The description only restates that a single candidate and text note are involved, adding no format or length guidance of its own.

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

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

States a specific verb and resource — 'add a text note to one candidate's activity history' — plus the underlying endpoint. This clearly separates it from read-side siblings like traffit_get_candidate_activities, which an agent might otherwise pick for note-related 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?

Gives clear usage context ('Scope: employee', one candidate per call) and an explicit safety rule: 'do not repeat a call that succeeded.' It stops short of naming the read alternative for inspecting existing notes, so routing guidance is strong but not exhaustive.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description is not required to carry the safety profile. It adds genuine value by listing the response payload sections (contact data, status, files, custom fields) in the absence of an output schema, but it says nothing about error behavior for a missing id or about the mismatch between a 'candidate' resource and the /employees/{id} path.

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 the verb and returned payload. The trailing 'GET /employees/{id}' is essentially redundant restatement of the operation, but the overall text is tight 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 one-parameter read-only getter with no output schema, enumerating the returned fields is exactly the compensating detail an agent needs. Only minor gaps remain (not-found behavior, relationship to the per-aspect get_candidate_* siblings).

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% — candidate_id is documented as a numeric id — so the schema does the work. The description only echoes 'by id' and adds no format, type or validation detail beyond it, which is the baseline 3 case for a fully covered single parameter.

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

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

States a specific verb and resource ('Get one candidate by id') and enumerates what is returned (contact data, status, files list, custom fields), which separates it from traffit_list_candidates. It stops short of naming siblings explicitly, and the 'files list' payload overlaps conceptually with traffit_get_candidate_files, so the boundary with that sibling is not fully resolved.

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 statement of when to use this versus traffit_list_candidates, traffit_get_candidate_files or the other get_candidate_* variants; the agent must infer that from the name alone. 'Scope: employee' is an API-doc fragment with no operational meaning for tool selection.

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 'Scope: employee' and the underlying endpoint, which is genuinely useful permission/routing context, but it says nothing about pagination defaults, ordering, or how much history is returned by default — details an agent would want when the result set can be large.

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

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

Two short sentences: the core action with concrete examples first, then scope and endpoint. Nothing is padded and the most decision-relevant information 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?

No output schema exists, but the parenthetical ('notes, stage moves, mails') gives the agent a usable picture of the return content, and pagination controls are fully described in the schema. Only minor gaps remain, such as default ordering and whether the list is truncated.

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, sort, filter, and candidate_id are all documented in the schema; baseline 3 applies. The description adds no parameter-level meaning, and the endpoint string 'GET /employees/{id}/activities' arguably muddies things by referring to an employee path while the required parameter is candidate_id.

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

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

States a specific verb and resource ('List the activity history of one candidate') and enumerates concrete content types (notes, stage moves, mails), which distinguishes it from siblings like traffit_get_candidate_files, traffit_get_candidate_tags, and traffit_get_candidate_jobs. It does not explicitly name those siblings, but the examples make the boundary clear enough to choose correctly.

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 'activity history of one candidate' but there is no explicit when-to-use or when-not guidance, and no comparison against the many sibling candidate-scoped getters. The agent must infer that this is the tool for timeline/audit data rather than files, jobs, or 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 already declare readOnlyHint=true, so the safety profile is covered. The description still adds real behavioral context beyond that: the returned fields (file names and upload dates), the 'Scope: employee' permission framing, and the underlying GET path. It stops short of stating pagination or empty-result 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 compact fragments with zero filler: the payload is front-loaded, then scope, then the endpoint. Nothing to trim.

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 and the return fields named inline, an agent has everything needed to call it. Minor gap: no mention of result size limits or what happens when the candidate has no files.

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 the schema already documents it at 100% coverage ('The candidate id (numeric id)'). The description's 'one candidate' merely confirms the same binding, adding no new syntax or format detail, 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?

Specific verb (list) plus the exact resource (files of one candidate) and even the shape of the returned data (file names and upload dates). A reader can distinguish it instantly from sibling endpoints like get_candidate_activities or get_candidate_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?

Usage is only implied by the phrase 'of one candidate' – it is clear this operates on a single candidate rather than listing across candidates, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative for related needs (e.g., activities or jobs for the same candidate).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered before the description is read. The description adds the underlying route (GET /employees/{id}/recruitments), which usefully explains why 'candidate' maps to 'employee' in the API, but says nothing about volume, pagination, or what an empty result means.

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 the purpose before the implementation detail. Every clause carries information, though the raw endpoint string is more developer-facing than agent-facing.

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 this is nearly sufficient, but with no output schema the agent has no idea what a 'job' record contains or whether results are paginated. A brief note on the returned shape would close the only real gap.

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

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

Schema description coverage is 100% and the single parameter candidate_id is fully documented in the schema as a numeric id. The description adds no format, source, or validation detail beyond that, so the baseline 3 applies.

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

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

"List the jobs (recruitments) a candidate takes part in" gives a specific verb and resource, and the parenthetical disambiguates 'jobs' as recruitments. It is clear what is returned at a high level, though it never contrasts itself with the close sibling traffit_list_job_candidates, which operates on the same two entities from the opposite direction.

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?

"Scope: employee" hints that this is the single-candidate view rather than a global job listing, which implies when to reach for it over traffit_list_jobs. However there is no explicit when-to-use statement or exclusion naming an alternative, so 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?

The readOnlyHint annotation already establishes this as a safe read operation, and the GET endpoint reinforces that. The description adds the scope and endpoint but does not cover pagination, response shape, or any rate-limit/auth context.

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

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

Two short sentences, front-loaded with the purpose and followed by scope and endpoint. There is no redundant wording.

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 list tool with complete schema coverage and annotations, the description gives enough context to invoke it correctly. It could be slightly richer about what a 'source record' contains, but the core need is met.

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 candidate_id is already well documented in the schema. The description only implicitly mentions 'one candidate' and adds no syntax 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?

The description states a specific verb and resource: list source records for one candidate. 'Where one candidate came from' clearly differentiates it from the broader list_sources sibling and from other get_candidate_* subtools.

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 implies the tool is used to retrieve source records for a specific candidate, but does not explicitly state when to use it instead of list_sources or get_candidate. No exclusions or prerequisites are provided.

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 the employee scope constraint and the underlying endpoint, which is genuine context, but says nothing about pagination, ordering, or what an empty result means for a tag list.

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 purpose, with zero filler. The raw endpoint string is marginal value for an agent but costs almost nothing.

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

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

For a one-parameter read-only lookup with a fully documented schema and no output schema, the description is minimally sufficient. It could do more by noting the return shape (a list of tag objects) or that tags may be empty, which an agent needs to interpret 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 coverage is 100% with a single required parameter already documented as "The candidate id (numeric id)." The description adds nothing about the id format or where to obtain it, so this sits at the baseline for a fully documented 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 the tags of one candidate"), which clearly separates it from the many sibling traffit_get_candidate_* tools covering jobs, files, sources, activities. It stops short of naming which sibling to use for the candidate's other sub-resources, but 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. "Scope: employee" implies a permission/role precondition but never states what to do if the caller is not an employee scope, leaving usage 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 declares this is a safe read, so the description mainly confirms the single-record, id-addressed nature and cites the underlying endpoint. It adds no information about error behavior (e.g. unknown id) or the shape of the returned client.

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 action and with zero filler. The telegraphic 'Scope:' and raw path fragments are efficient if slightly cryptic for an agent unfamiliar with the API.

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 annotations covering safety, the essentials are present. With no output schema, though, the description never indicates what a client record contains, which is a meaningful gap for a get-by-id tool.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema as a numeric id string. The description's 'by id' restates that without adding format, sourcing, or validation guidance, 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?

'Get one client company by id' states a specific verb and resource, and the word 'one' implicitly separates it from the sibling traffit_list_clients. It does not explicitly name the sibling, so it falls just short of a 5.

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

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

The 'Scope: client' note hints at the required API scope, which is genuine usage context. However, there is no explicit statement of when to use this versus traffit_list_clients or how to obtain a client_id, leaving usage only implied.

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

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

readOnlyHint=true already tells the agent this is a safe read; the description adds the underlying endpoint (GET /crm_persons/{id}) and the scope token, which help an agent map the call to the CRM entity. It says nothing about behavior on a missing/invalid id (404 vs empty result) or what is returned.

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 action, no filler. 'Scope: crm_person' is mildly redundant with the resource already named in the first 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?

A one-parameter read tool with readOnlyHint is nearly self-explanatory, but with no output schema the description never indicates what a contact record contains or what happens when the id does not resolve.

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 contact_id is fully documented as a numeric string id, so the schema carries the load. The description's 'by id' adds nothing beyond it – baseline 3.

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

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

Specific verb+resource: 'Get one contact person by id', which is clearly a single-record fetch and distinguishable from list_contacts. It does not, however, differentiate itself from traffit_get_client, which an agent could plausibly confuse with a contact lookup.

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?

'by id' implies the tool is for when a known identifier is in hand, versus the list_contacts sibling for discovery, but this is left implicit. No when-not-to-use or prerequisite guidance 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 readOnlyHint=true, so the safety profile is covered; the description adds what the agent would not otherwise know – the returned payload includes client, responsible people, status and custom fields, and the underlying domain scope. It stops short of noting error behavior for missing ids or any auth requirements.

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

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

Two compact sentences, front-loaded with the action and the returned fields. The trailing 'GET /recruitments/{id}' endpoint restatement is mild filler but cheap and occasionally useful for API-savvy callers.

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 readOnlyHint declared and no output schema, the description supplies exactly the missing piece – the shape of the returned job record – plus the scope. Nothing needed to call it 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?

Schema coverage is 100% for the single job_id parameter and the schema already specifies 'numeric id', so the description's 'by id' adds nothing new. Baseline 3 applies because 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 ('Get one job (recruitment) by id') and enumerates what comes back (client, responsible people, status, custom fields). The 'one job ... by id' phrasing implicitly separates it from traffit_list_jobs, 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?

Usage is implied only: 'one job by id' suggests the single-record lookup versus the list variants, and 'Scope: recruitment' hints at the domain. There is no explicit when-to-use or when-to-prefer traffit_list_jobs / traffit_get_candidate_jobs.

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

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

readOnlyHint=true already declares the safe read profile, so the description's burden is lower. It adds the REST endpoint (GET /recruitments/{id}/states/counter), confirming a non-mutating single-resource fetch, but says nothing about whether stages with zero candidates appear, whether counts are current, or anything about the response shape.

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

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

Two short, front-loaded sentences with the purpose first and the endpoint last. 'Scope: recruitment' and the raw path add little for an agent but cost almost nothing; there is no padding or repetition.

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

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

For a trivial one-parameter read tool with readOnlyHint, the description is close to sufficient. However, with no output schema present, the description should have characterized the return value (a per-stage count mapping) rather than leaving the result shape to inference.

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%, so the schema fully documents job_id. The description's 'one job' phrasing reinforces that job_id scopes to a single job but adds no format or id-source detail beyond the schema — baseline 3.

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

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

The description states a specific verb and resource ('Count the candidates in each stage of one job') and constrains scope to a single job, which implicitly separates it from traffit_list_stage_candidates and traffit_list_job_states. It stops short of naming those siblings explicitly, so the differentiation is inferable rather than stated.

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 can infer this is the counting aggregate versus the listing siblings, but the description never says when to prefer it or what it replaces. 'Scope: recruitment' is a namespace tag, not guidance on alternatives or preconditions.

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

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

readOnlyHint=true already declares the safe-read profile, so the description only needs to add context. It contributes the HTTP endpoint mapping and scope, but says nothing about error behavior for missing ids, permissions, or rate limits.

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

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

Three short fragments, front-loaded with the core action; nothing is padded. The 'Scope: user' fragment is slightly opaque but costs little.

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?

A simple single-param read is adequately covered for invocation, and annotations carry the safety profile. However, with no output schema, the description gives no hint of what a user record contains, leaving the return shape entirely unspecified.

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 user_id parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no format, validation, or example detail beyond 'by id'.

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

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

States a specific verb and resource ('Get one Traffit user by id') and pins down the API endpoint (GET /users/{id}), which is concrete. It implicitly distinguishes itself from traffit_list_users via 'one ... by id', but never names the sibling 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 guidance on when to use this versus traffit_list_users or any other sibling; the only usage signal is the generic 'by id'. An agent must infer the selection criteria itself.

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

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

The readOnlyHint already establishes the safety profile. The description adds useful behavioral context by saying the response includes stages and by naming the underlying GET endpoint and dictionary scope.

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 the core action and return shape. There is no wasted 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 simple read-only lookup with full schema coverage and no output schema, the description is nearly complete. It clarifies that stages are included but does not mention not-found behavior, which is a minor gap.

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

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

The single workflow_id parameter is fully documented in the schema, including that it is numeric and can come from a job's workflow_id. The description adds little beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: get one recruitment workflow by id, including its stages. The scope and endpoint reinforce exactly what the tool does.

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 usage is implied: call this when you have a workflow_id and need that workflow with stages. It does not explicitly say when to use it versus alternatives, though there is no obvious sibling workflow-fetching tool.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds a useful return contract ('total_count and items') and mentions scope/endpoint, but 'Scope: employee' and 'GET /employees/' are opaque for a candidates tool and no pagination defaults or permission details are explained.

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 short and front-loaded, first stating the operation and capabilities, then the return shape. The terse 'Scope: employee. GET /employees/.' fragments are ambiguous and do not clearly earn their 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?

Given the fully documented schema and read-only annotation, the description supplies the key return information ('total_count and items') and operation scope. It does not explain item structure or sibling routing, but it is adequate for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the schema fully documents page, sort, filter, and page_size including comparison operators and sort direction enum. The description adds filter field examples such as name and lastname, but adds no syntax or semantic detail beyond the schema, 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 gives a specific verb and resource ('List candidates in the ATS') and names the supported capabilities (paging, filters, sort). It does not explicitly distinguish itself from siblings such as traffit_list_job_candidates or traffit_list_stage_candidates, 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?

Usage is implied: call this to list candidates with paging, filtering, and sorting. There is no explicit when-to-use/when-not guidance and no mention of alternatives like traffit_get_candidate for single records or traffit_list_job_candidates for job-scoped listings.

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 the HTTP endpoint ('GET /clients/') and confirms the read-only, scoped nature, but says nothing about pagination metadata, default/maximum result windows beyond the schema, or rate limits.

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

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

Two short sentences, front-loaded with the purpose. The trailing 'Scope: client. GET /clients/.' fragment is slightly staccato but carries real information about the resource path.

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

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

For a read-only list tool with full schema coverage, no required parameters and no output schema, the definition supplies enough to invoke it correctly. The remaining gap is that nothing hints at the shape of the paginated response or how to page past the max page_size.

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% – the schema documents page, page_size, sort and the nested filter/comparison structure in detail. The description only restates 'paging, filters and sort' without adding syntax or examples, 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?

Specific verb + resource: 'List client companies (CRM)' with paging, filters and sort, plus the endpoint GET /clients/. It is clearly a bulk-enumeration counterpart to the singular traffit_get_client, though that sibling is not named explicitly and the CRM-company scope has to be inferred.

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 traffit_get_client, traffit_list_contacts, or traffit_list_crm_activities. The only guidance is implicit in the word 'List' and the mention of paging/filters; there are no exclusions or prerequisites.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description's main added value is confirming this is a scoped GET on /crm_persons/. It says nothing about pagination limits, whether the list is filtered to the authenticated client, or what a contact record contains — modest value beyond the annotation.

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

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

Two terse sentences, front-loaded with the resource and audience, with zero filler. The endpoint fragment is mildly redundant but gives useful API grounding; nothing is buried or over-explained.

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 characterize the returned contact records at all (fields, ordering default, or that filtering supports custom fields). For a nested-filter list tool this leaves a gap, although the readOnly annotation and full param coverage keep it close to adequate.

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%: page, page_size, sort and filter (including the nested value/comparison shape) are all documented with examples in the schema. The description adds no parameter guidance, so the baseline 3 applies — the schema does all the work 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 contact people (crm_persons) of client companies') and pins the API scope as crm_person with the underlying endpoint. This separates it from traffit_get_contact (single record) and traffit_list_clients, though the description 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 phrase 'of client companies' implies the use case (browsing contacts attached to clients), but there is no explicit statement of when to use this versus traffit_list_clients or traffit_get_contact, and no exclusions or prerequisites. Usage must be inferred from the scope line.

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

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

readOnlyHint=true already declares the safety profile, so the description only adds the API scope and endpoint path. It says nothing about pagination behavior, total counts, or what a page of results contains beyond what the schema and annotations already provide.

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 fragments, front-loaded with the action and resource, with zero wasted words. It is terse to the point of omitting useful routing context, which is the only thing keeping it from 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?

A read-only list tool with a fully documented schema and no output schema; the description gives the resource, its scope, and the endpoint, which is enough to call it correctly. The unresolved question of whether candidate activities are included is the main 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 description coverage is 100% and the descriptions are detailed (sort example, filter comparison operators, page_size max 100), so the schema carries parameter meaning. The description adds no additional parameter guidance, which is the baseline-3 case.

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 CRM activities") and the parenthetical enumerates what counts as an activity (calls, meetings, notes). It does not differentiate from the closely related sibling traffit_get_candidate_activities, 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?

There is no when-to-use guidance and no alternatives named. The scope note (clients and contacts) only indirectly hints at how this differs from traffit_get_candidate_activities, leaving the agent to infer which tool 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the API scope and endpoint path, but does not mention pagination, sorting, filtering behavior, or return format beyond what the schema already documents.

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

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

The description is two short sentences plus the endpoint path, with the core purpose front-loaded. Every sentence contributes useful information without redundancy.

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

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

The tool is a straightforward read-only list operation with fully documented parameters and a readOnlyHint annotation, so the description does not need to explain return values or safety. It could more explicitly clarify the relationship to sibling list tools, but otherwise it is sufficient.

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 parameters including `job_id`, `page`, `sort`, `filter`, and `page_size` are already well documented. The description adds no parameter-level semantics beyond the schema, which meets the baseline for high-coverage schemas.

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 candidates attached to one job. This distinguishes it from the general `traffit_list_candidates` sibling, though it does not explicitly contrast with `traffit_list_stage_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?

The phrase 'attached to one job' implies when to use the tool, but there is no explicit when-to-use guidance or comparison with alternatives such as `traffit_list_candidates` or `traffit_list_stage_candidates`.

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 description is not obligated to restate that this is a safe read. It adds the endpoint path, which gives a hint about underlying resource shape, but says nothing about result volume, total-count/pagination metadata, or cost of broad filters. Adequate against a low annotation bar, but thin on behavior beyond 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, front-loaded clauses: the action and capabilities come first, the scope and endpoint second. No filler, no restatement of the title, nothing that could be cut without losing information.

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

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

No output schema exists, so the description carries some burden for return shape, yet it never says what a job record contains or whether pagination metadata (total pages/count) is returned. For a read-only list tool with fully documented parameters the gaps are survivable, but not complete.

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

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

Schema description coverage is 100%, including defaults (page 1, page_size 20/max 100), a filter example, and the comparison enum, so baseline is 3. The description adds nothing parameter-specific — 'with paging, filters and sort' merely names what the schema already fully documents, and does not clarify the nested filter/sort object semantics further.

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

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

States a specific verb and resource ('List jobs (recruitments)') plus the three capabilities it exposes (paging, filters, sort) and the underlying endpoint GET /recruitments/. The parenthetical synonym 'recruitments' is genuinely useful terminology mapping. It doesn't explicitly distinguish itself from traffit_list_job_candidates or traffit_get_job, but the list-vs-get wording makes the boundary inferable.

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?

'Scope: recruitment' is the only contextual hint; there is no explicit when-to-use, when-not-to-use, or named alternative. An agent must infer that this is the browsing/query tool to use instead of traffit_get_job when no ID is known. Usage is implied by the endpoint semantics 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 safety is covered. The description adds the concrete endpoint and scoping ('of one job', 'Scope: recruitment'), which helps confirm this is a per-job read, but says nothing about pagination behavior, result ordering, or what happens when the job has no stages.

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 the purpose and followed by scope and endpoint. 'Scope: recruitment' and the path are mildly redundant with 'GET /recruitments/{id}/states', but nothing is wasted or 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?

The tool takes five parameters including nested filter/sort and has no output schema, so the description could have explained the returned stage objects or paging behavior. With a fully documented schema it is adequate, but it leaves the agent without guidance on the return shape or on the overlap with traffit_get_job_stage_counts.

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, sort, filter, and job_id are all self-documented. The description adds no extra meaning to the nested filter/sort objects or the pagination parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the pipeline stages (states) of one job') plus the underlying endpoint GET /recruitments/{id}/states, so the agent knows exactly what it returns. It does not, however, distinguish itself from the sibling traffit_get_job_stage_counts, which targets the same sub-resource.

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: the agent can infer it should call this when it needs the stage list for a known job_id. There is no explicit when-to-use, no mention of when to prefer traffit_get_job_stage_counts, and no stated prerequisites beyond the required job_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, so safety is covered, and the description reinforces that by framing it as a plain GET on /sources. It adds nothing about pagination behavior (beyond what the schema says), result ordering defaults, total counts, or auth requirements, so it is adequate but thin on 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 short sentences, front-loaded with the resource being listed; nothing is redundant. It is written as telegraphic fragments ('Scope: source. GET /sources.') rather than full clauses, but every fragment 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, the description could have said what a returned source record contains or whether the list is paginated by default, and it does neither. The schema fully covers inputs, so the gap is limited to the return side, but it leaves the agent guessing about result 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 all four parameters (page, sort, filter, page_size) are documented inline in the schema, including the nested filter comparison enum and examples. The description adds no additional parameter meaning, 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 says precisely what is returned: a list of sources (job boards, referrals), and it names the resource scope ('Scope: source') plus the underlying endpoint (GET /sources). That is enough to distinguish it from the candidate-specific sibling traffit_get_candidate_sources, though it never names that sibling 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 statement of when to use this instead of traffit_get_candidate_sources, traffit_list_candidates, or any other list tool. 'Scope: source' hints at the resource boundary but gives no exclusions, prerequisites, or selection criteria.

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 the stated GET endpoint plus 'Scope: recruitment' add confirming context about the operation's nature. No information is given about pagination behavior or result volume, though those are partly implied by the schema's page/page_size 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, front-loaded with what is listed, then the prerequisite, then the scope and 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 read-only, paginated list tool with fully documented parameters, the description covers purpose, prerequisite and scope adequately. The absence of any return-shape note is a minor gap given there is no output schema, but the tool's contract is otherwise clear.

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, filter, job_id and state_id all documented in the schema itself. The description adds only the provenance of state_id via traffit_list_job_states, so baseline 3 applies.

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

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

States a specific verb and resource with explicit scoping ('candidates that are now in one stage of one job'), which distinguishes it from sibling list tools like traffit_list_candidates and traffit_list_job_candidates. The HTTP path reinforces the resource nesting.

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 supplies the prerequisite for calling it: 'Get stage ids from traffit_list_job_states,' naming the specific sibling that produces one of the required ids. It lacks an explicit statement of when to prefer this over traffit_list_job_candidates, but the context is otherwise 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 already declare readOnlyHint=true, so the safety profile is covered and the description's bar is lower. It adds only the scope and endpoint path ("Scope: talent. GET /talents."), saying nothing about pagination behavior, total counts, or whether the list is truncated at page_size — useful context that is absent.

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 with the core purpose front-loaded; nothing is padded. The trailing "GET /talents" is somewhat redundant with "Scope: talent" but is cheap and occasionally useful for debugging.

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?

A simple, parameterless-required, read-only list tool with fully documented parameters and annotations covering safety. However, with no output schema, the description gives no hint about the shape of returned pool records or pagination metadata, leaving a small but real gap.

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

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

Schema description coverage is 100% and the schema itself explains page, page_size (default 20, max 100), sort, and filter with examples. The description contributes nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("List talent pools") and adds a clarifying gloss, "named groups of candidates," so an agent unfamiliar with the domain knows what a talent pool is. No sibling tool offers an overlapping capability, so no sibling differentiation is required.

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 by the verb "List" and the "Scope: talent" tag; there is no explicit statement of when to reach for this versus e.g. traffit_list_candidates or the get_* lookups. With no competing alternative for talent pools, the risk is low, but the description does no routing work.

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

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

The readOnlyHint=true annotation already establishes this is a safe read, so the description's burden is lower. It does add that group and permission-group data come back with each user, but says nothing about volume, pagination expectations, or that results are scoped to the caller's account permissions beyond the terse 'Scope: user'.

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 the purpose followed by the scope and endpoint. The raw 'GET /users/.' is near-redundant but cheap, 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 simple read-only list tool with a fully documented schema and no output schema, the description covers what the tool returns at a high level (users with groups and permission groups). It stops short of describing the response shape or pagination behavior, which matters somewhat 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?

Schema description coverage is 100%, and the schema already documents page, page_size, sort, and the nested filter object with comparisons and examples. The description adds no parameter-level meaning, which is acceptable at full coverage but earns only 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 and resource ('List users of the Traffit account') and adds the notable payload detail that groups and permission groups are included. The plural 'List users' plus 'Scope: user' distinguishes it from the sibling traffit_get_user, though the contrast is implicit rather than stated.

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?

'Scope: user' hints at the permission context in which the call is valid, and 'List' implies enumeration rather than a single-record fetch. However, no explicit when-to-use guidance or pointer to alternatives like traffit_get_user for a single user is given.

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