CATS MCP by usefulapi

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

Annotations already flag the write/idempotent/destructive profile, and the description adds genuinely new behavioral facts: the explicit confirm gate, the absence of any outbound send side effect despite email/text types, and the duplicate-accumulation risk from repeated calls. These are consequences an agent cannot derive from readOnlyHint/destructiveHint alone.

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?

Leads with the gating fact ('WRITE: Requires confirm:true'), then purpose, then the non-obvious caveat, then the endpoint. Four short clauses with no filler and the highest-risk information front-loaded.

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

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

With 6 fully documented parameters, no output schema, and annotations covering the safety profile, the description is sufficient to call correctly. It does not say what the call returns (e.g. the new activity id), which matters slightly for a create tool whose result might be chained, but that is a minor gap.

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

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

Schema coverage is 100% and each parameter already carries a description, including the enum on 'type' and the guidance to use 'other' for a plain note. The description's 'a call, meeting, note...' only loosely gestures at the enum values, so it adds no semantics the schema does not already provide — baseline 3.

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

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

States a specific verb and resource ('log an activity ... on a candidate's record') and names the concrete subtypes (call, meeting, note). The trailing 'POST /candidates/{id}/activities' plus the fact that siblings like cats_list_candidate_activities are read tools makes the write/read distinction 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?

Gives a hard precondition ('Requires confirm:true') and an explicit exclusion — it will not send email/SMS even for type 'email' or 'text_message' — which is exactly the kind of guidance an agent needs before choosing it. It stops short of naming the read-side siblings (cats_list_candidate_activities, cats_list_activities) that an agent would use instead when logging is not the goal.

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 that every trigger on the target status is sent with fire=false, that CATS enforces trigger semantics while externally configured webhooks may still fire, that the change is written to status history, and gives the underlying POST /pipelines/{id}/status endpoint. That is meaningful side-effect disclosure for a destructive, non-idempotent operation.

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

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

Front-loaded with the WRITE marker and the confirm requirement, and most sentences carry distinct information (ID sources, trigger suppression, history, endpoint). The phrase 'Requires confirm:true' appears twice, which is wasted repetition in an otherwise tight description.

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 tool with no output schema, the description covers the safety gate, side effects, and ID provenance, which is nearly everything an agent needs. The only omission is any statement about the response body or what the agent should verify afterward, which is a minor gap 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 coverage is 100%, so the baseline is 3; the description adds value by naming the source tools for pipeline_id and status_id and reinforcing that the status must belong to the pipeline's workflow. It still doesn't clarify the exact semantics of the 'confirm' flag beyond restating the requirement.

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 ('change the status of a pipeline') and immediately glosses it as moving a candidate between workflow stages with concrete examples (Interviewing, Offered, Rejected). This is clearly distinguishable from read-oriented siblings like cats_get_pipeline or cats_list_workflow_statuses.

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

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

Explicitly routes the agent to cats_list_candidate_pipelines for the pipeline id and cats_list_workflow_statuses for the status id, which is exactly the prerequisite chain an agent needs. It lacks an explicit 'do not use when…' clause (e.g., for creating a new pipeline or adding an activity), so it falls short of a 5.

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

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

Annotations already flag destructive/non-idempotent/openWorld, but the description adds context annotations cannot express: the mandatory confirm flag, the refusal-on-duplicate behavior and its default, the fact that each call creates a new record, and the deliberate absence of email or login side effects. That is meaningful disclosure of concrete side-effect boundaries for a write.

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

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

Front-loads 'WRITE: Requires confirm:true' before any detail, then packs behavior, defaults and side-effect exclusions into a few dense clauses 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?

Strong on preconditions and side effects for a 17-parameter mutation, but with no output schema the description never says what comes back (e.g., the new candidate id or the duplicate match found), which is the one thing an agent still has to guess.

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 17 parameters at 53% schema coverage, the description only illuminates 'name', 'notes', 'confirm' and 'check_duplicate' (including its default). It adds real value on the duplicate flag but says nothing about owner_id, source, key_skills, phone_type, or the address fields, leaving a sizeable coverage gap unaddressed.

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?

A specific verb plus resource ('create one candidate record') with an explicit data scope ('personal data ... name, optional contact details and notes') and the underlying endpoint POST /candidates. It is trivially distinguishable from the get/list/search candidate siblings.

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

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

States the precondition (confirm:true required) and the duplicate policy (refuses when check_duplicate=true, which is the default), plus negative scope: no email is sent and no login is created. It does not explicitly route to an alternative such as search-before-create or an update tool, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=false and openWorld=true, and the description reinforces the write/idempotency profile rather than contradicting it. It adds genuinely new behavioral context: the confirm:true gate and that "CATS may notify the assignee" — a side effect an agent cannot infer from annotations or 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?

Three tight sentences with the safety gate front-loaded ("WRITE: Requires confirm:true") before the operation itself. Every clause carries information — idempotency, notification side effect, endpoint — 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 7-parameter mutation with no output schema, the description covers the precondition, side effects and retry semantics well. The remaining gap is return behavior — nothing says what the caller gets back (e.g. the new task id) to chain into cats_get_task — which matters with no output schema to fall back on.

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 the about_type enum, priority range and the about_id/about_type pairing. The description only restates the about/assignee concept at a high level, adding no syntax or format 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?

Specific verb+resource ("create a task in CATS") with scope qualifiers: what it can be attached to (candidate, contact, company, job) and that it can be assigned. This clearly separates it from the read siblings cats_get_task, cats_list_tasks and cats_list_candidate_tasks.

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

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

States the hard precondition "Requires confirm:true" and warns that each call creates a new task (not idempotent), which is actionable guidance against blind retries. It does not name an alternative (e.g. cats_add_candidate_activity) or say when a task is preferable to an activity log entry, so it stops short of full routing guidance.

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

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

The parenthetical 'read-only, although it is a POST' is genuinely valuable: it pre-empts the natural inference that a POST with a conditions body mutates data, aligning the agent with readOnlyHint=true. It also discloses pagination and the underlying endpoint. It does not describe result shape or what empty results look like, but annotations already carry the safety profile.

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

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

Front-loaded with purpose, read-only caveat, and field list, all in a compact block. The trailing ellipsis in the field enumeration and the run-on condition/filter sentence make it slightly ragged, but there is little 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 read-only filtered-list tool with a fully described schema and no output schema, this covers the essentials: what can be filtered, how conditions combine via the schema, and that results are paged. The only real omission is any mention of the next_page continuation contract that the schema references.

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 a 3 is the baseline. The description adds real value on top by enumerating concrete filterable field paths (emails.primary, address.city/state/postal_code, current_employer, key_skills, is_hot) and restating the filter vocabulary in the same breath as the field list, which helps the agent compose valid conditions.

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 (filter candidates) and enumerates the filterable fields, so the agent knows exactly what kind of query this performs. It never names the obvious competitors (cats_search_candidates, cats_list_candidates), so the boundary between 'filter' and 'search'/'list' remains unstated.

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 detailed field and filter enumeration implies this is for structured multi-condition queries, and the paging note hints at iteration. But with three closely related siblings (list_, search_, filter_candidates) in the toolset, the description gives no explicit 'use this when…' rule and no exclusion of the alternatives.

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

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

The parenthetical '(read-only, although it is a POST)' resolves a real ambiguity that the annotations alone (readOnlyHint=true) would leave confusing for an agent scanning HTTP verbs. It also discloses pagination behavior, which annotations do not cover. It stops short of describing the response payload shape or the 10-condition cap's implications.

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 capability and filterable fields front-loaded, followed by the condition shape, pagination, and endpoint. Nothing is repeated or 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 4-parameter filtered-search tool with no output schema, the description covers what can be filtered, the condition grammar, and paging. The main remaining gap is the return payload (what a pipeline record looks like), which the agent must discover from sibling tools.

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 would be 3, but the description adds pipeline-specific filterable fields (candidate_id, job_id, status_id, rating, dates) that the generic schema field example does not supply. It also restates the {field, filter, value} condition shape, reinforcing the required structure.

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 ('Filter pipelines') and enumerates the filterable fields, so the agent knows this is a search endpoint rather than a plain list. It does not explicitly name the sibling it replaces (e.g. cats_list_pipelines) or explain the boundary versus cats_get_pipeline, so sibling differentiation is left implicit.

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

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

Usage is implied by the field list and the POST /pipelines/search endpoint, and 'Paged' hints at iterative use with next_page. However, there is no explicit statement of when to choose this over cats_list_pipelines or how to combine it with the get-by-id tool, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds '(personal data)', a useful note that the payload carries PII, and the endpoint mapping, but says nothing about permissions, error behavior, or 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 fragments with no filler; the identifier-based scope and PII note land immediately. The REST route is slightly redundant with the tool name but helps agents map to API docs.

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 with no output schema, the description should at least sketch what comes back (candidate record fields) or what a missing id yields. It gives a high-level 'one candidate (personal data)' but leaves the return contract and failure mode 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 parameter is documented in-schema as 'CATS candidate id' with a positivity/range constraint. The description adds nothing beyond that, which is the expected baseline when the schema already 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: fetch one candidate by id, plus the underlying REST route GET /candidates/{id}. The 'by id' scope implicitly separates it from cats_list_candidates, cats_filter_candidates, and cats_search_candidates, 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?

'by id' signals the required input and thus implies the lookup-by-identifier use case, but there is no explicit statement of when to prefer this over the filter/search/list siblings, nor any prerequisite or error expectation (e.g. what happens for an unknown 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint mapping (GET /companies/{id}), which is mildly useful for agents mapping to API behavior, but it says nothing about what happens with an invalid or unknown id.

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

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

Two short fragments with zero filler and the key information (single company, id-based) front-loaded. The HTTP path restatement is marginally redundant but cheap and aids API mapping.

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-entity fetch with full schema coverage and clear read-only annotations, this is minimally adequate. With no output schema, though, a hint about what a company record contains or how a missing id is surfaced would have closed the remaining gap.

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

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

Schema coverage is 100% and the single company_id parameter is documented as "CATS company id" with a positive-integer constraint. The description's "by id" adds nothing 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?

"One company by id" states a specific verb (fetch a single company) and resource, and the "by id" qualifier implicitly distinguishes it from cats_list_companies and cats_search_companies. It is clear but relies on the name and sibling context rather than explicitly naming the alternatives.

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

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

There is no guidance on when to use this versus cats_list_companies or cats_search_companies, and no mention of prerequisites such as needing a valid company id. The usage is only inferable from "by id" and the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description contributes the PII flag and the underlying REST path, but says nothing about what an unknown id yields or whether the lookup is rate-limited.

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 with the resource and scope front-loaded; nothing is padded or repeated. It reads as a terse fragment rather than a full sentence, but every token 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?

There is no output schema, so the description is the only place the return value could be characterized, and it says only 'One client contact' without listing fields or describing error behavior for a missing id. For a single-parameter read tool this is adequate but leaves a 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% — contact_id is typed as a positive integer with a documented description — so the schema carries the parameter semantics. The description only restates 'by id' and adds no format, source, or range guidance beyond it.

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

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

States a specific verb ('Get') and resource ('contact') scoped to a single record by id, and the parenthetical '(personal data)' signals the PII nature. It implicitly distinguishes itself from cats_list_contacts and cats_search_contacts by being id-based, but 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?

No statement of when to use this versus cats_list_contacts or cats_search_contacts, and no prerequisite such as 'you must already have a contact_id'. The id-scoped framing hints at usage but leaves the agent to infer the routing decision.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the response includes the job's description and gives the REST path, but omits error behavior, auth needs, 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 with the core resource and endpoint front-loaded, and no filler. This is appropriately sized for a simple single-record get.

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 whose annotations already cover safety, the description states what is returned (the job plus its description) and the endpoint. It is nearly complete, though not-found behavior or id-discovery guidance is absent, which is minor here.

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 sole job_id parameter is documented as 'CATS job id.' The description's 'by id' and endpoint path add no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description specifies retrieving a single job order by id and mentions that the job's description is included. The phrase 'One job order by id' implicitly distinguishes this single-record get from the many list/search siblings, though it does not name an alternative.

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 guidance or exclusion. It only implies use when a job id is already known, and does not point to cats_list_jobs or cats_search_jobs for discovering ids.

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 annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by defining the pipeline concept and exposing that this is a GET endpoint, but it does not discuss error behavior, authentication, or 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?

The description is two short sentences with zero waste. The core purpose and resource definition are front-loaded, followed by the endpoint for technical clarity.

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

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

For a simple one-parameter read tool with annotations and full schema coverage, the description provides enough context to select and invoke it correctly. It is slightly incomplete only because it does not mention return shape or error conditions, though those are less critical for a basic getter.

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 pipeline_id parameter is already documented in the schema as 'CATS pipeline id.' The description reinforces that lookup is by id but adds no additional format, validation, or semantic 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: get one pipeline by id. It also clarifies that a pipeline is a candidate on a job and includes the underlying endpoint GET /pipelines/{id}, which clearly distinguishes it from list/filter pipeline siblings.

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

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

Usage is implied by the phrase 'by id' and the contrast with list/filter siblings, but the description does not explicitly say when to use this tool versus cats_list_pipelines, cats_filter_pipelines, or cats_get_pipeline_status_history. No exclusions or alternatives are named.

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 usefully adds what the payload contains (status, who, when), but says nothing about ordering, retention window, or how paginated history is traversed.

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

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

Two tight sentences with the substantive content (what the history contains) front-loaded and the endpoint as a trailing reference. 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 tool with a fully described three-parameter schema, no output schema, and annotations carrying the safety profile, the definition covers what an agent needs. The remaining gap is ordering/sort direction of the history, 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?

Schema description coverage is 100%, so pipeline_id, page and per_page are already documented, including the next_page chaining hint. The description only reiterates the {id} path parameter via the endpoint string and adds no new semantic 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 resource (a pipeline's status-change history) and the fields returned (status, who, when), plus the underlying endpoint. It is distinguishable from the mutating sibling cats_change_pipeline_status and from cats_get_pipeline, though it never names them 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: read this to see how a pipeline's status evolved. There is no explicit when-to-use or when-not, and no pointer to siblings such as cats_change_pipeline_status for making a change or cats_get_pipeline for current state.

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 goes beyond that by disclosing the return payload — id, mode with its two known values, and subdomain — which is genuinely useful 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?

Two short sentences: the resource and its returned fields are front-loaded, with the endpoint path as a compact trailing anchor. Nothing is redundant or 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?

With no output schema, the description must carry the return shape and it does name the three key fields and mode's enum values. It stops short of a full field list, but for a trivial zero-parameter context call this is sufficient to invoke 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?

The tool takes zero parameters, so the baseline is 4; there are no argument semantics to explain, and the description correctly spends no words on 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?

The description names the resource precisely as the CATS site (account) tied to the current API key, plus the fields returned (id, mode, subdomain) and the underlying endpoint GET /site. That scope implicitly separates it from sibling lookups such as cats_get_company or cats_get_contact, 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?

Usage is only implied: an agent can infer this is the call to make when it first needs account/mode context (e.g., to know whether the key is recruiter or employer scoped). There is no explicit 'use this when...' statement, no prerequisites, and no named alternative or exclusion.

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 only the REST path, with no note on error behavior for a missing id, authorization scope, or what a task record contains.

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 fragments with no wasted words, and the core scope leads. However, restating the raw REST endpoint is arguably low-value for an MCP agent and the brevity shades into under-specification rather than efficiency.

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?

This is a simple single-parameter read with full schema coverage, annotations covering safety, and no output schema, so the description needn't explain return values. Still, it offers nothing on failure modes or how the returned task relates to candidate/pipeline context in this API.

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 'task_id' documented as the CATS task id. The description's phrase 'by id' restates the schema rather than adding format or lookup 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?

The description states a single-item retrieval scoped by id and even names the underlying endpoint (GET /tasks/{id}), which implicitly distinguishes it from the bulk sibling cats_list_tasks. It is a fragment rather than a sentence, but the verb/resource/cardinality are all recoverable.

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

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

There is no guidance on when to call this versus cats_list_tasks or cats_list_candidate_tasks, and no mention of prerequisites such as needing a valid task id. The agent is left to infer usage entirely from the name and 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 the safety profile is covered. The description adds a modest amount: the activity types returned, that each entry carries its related record, and that results are paged. Auth needs, rate limits, and ordering are not 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?

A single front-loaded sentence with zero filler, ending with the endpoint for traceability. 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?

No output schema exists, and the description compensates by stating what the log contains and that each entry includes the record it's about. Pagination behavior is delegated to the schema, which covers it well; minor remaining gap is entry ordering.

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 are documented in the schema (including the useful 'pass the previous reply's next_page' hint). The description only says 'paged', adding no 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?

States a specific resource (activity log) and its scope ('site-wide'), plus enumerates what's in it (calls, emails, meetings, notes). 'Site-wide' implicitly distinguishes it from cats_list_candidate_activities, but does not name the alternative or state the contrast 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?

'Site-wide' hints that this is the unfiltered variant versus the candidate-scoped sibling, but the description never says when to choose one over the other. No prerequisites or exclusions are given; usage must be inferred from the scope word alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that results are paged and what kinds of activities appear, but says nothing about ordering, volume, or what happens on an invalid page/candidate.

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 with no filler; the resource and its contents come first and the endpoint trail last. It is efficient, though slightly under-informative rather than 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 three-parameter read-only list tool this is minimally adequate: the schema covers every parameter and the annotations cover safety. With no output schema, however, the description leaves the shape of an activity record (what fields identify a call vs a note) 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 description coverage is 100%, and the schema already documents page defaults, ranges, and the next_page handoff, so the baseline of 3 applies. The description adds nothing about candidate_id semantics or pagination behavior beyond the word 'paged'.

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 ('activity log of a candidate') and enumerates what the log contains (calls, meetings, notes, pipeline changes), plus the underlying endpoint. Scope is clear enough to separate it from the global cats_list_activities, though the sibling is never 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 only implied by the per-candidate scope: an agent can infer it should call this when it has a candidate_id. There is no statement of when to prefer cats_list_activities, cats_get_candidate, or cats_list_candidate_tasks, and no prerequisites or exclusions are 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that with the 'metadata only, contents never downloaded' scope limit and the underlying endpoint, telling the agent what will not happen as a result of the call.

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 plus an endpoint line, front-loaded with what is returned before the scope caveat. Nothing is padded; the endpoint snippet is marginally redundant with the tool name but cheap and clarifying.

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 rightly enumerates the returned fields, and pagination is fully handled by the schema. For a low-complexity read tool with rich annotations, this is nearly all an agent needs; only routing against sibling list tools 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%: page, per_page and candidate_id all carry descriptions including defaults and the next_page chaining hint. The description adds only the path shape GET /candidates/{id}/attachments, which lightly reinforces that candidate_id is a path identifier, so 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 the resource (a candidate's attachments) and enumerates the exact data returned (file names, sizes, resume flag), so the agent knows precisely what it gets. It does not explicitly differentiate from sibling list tools like cats_list_candidate_activities, 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?

Usage is implied by the resource name and the 'metadata only: file contents are never downloaded' constraint, which usefully tells the agent this is not a download endpoint. However, there is no explicit when-to-use statement, no mention of when to prefer cats_get_candidate or other list siblings, and no prerequisite guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds that this is a GET endpoint and enumerates returned fields. It does not add authentication, pagination, ordering, or rate-limit context beyond what the schema already provides.

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 definition is one sentence plus the endpoint, front-loaded with the resource and return fields and free of filler. It is appropriately sized for a simple list tool, though the endpoint is somewhat redundant.

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

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

For a simple read list with full schema coverage and safety annotations, the description supplies the core purpose and returned fields. It does not discuss pagination behavior, but the schema already documents page and per_page, and the annotations cover safety.

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, per_page, and candidate_id fully described in the schema. The description only implies candidate scoping and adds no syntax or semantics beyond what the schema provides, 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?

The description identifies the specific resource (a candidate's pipelines) and the returned data (rating, workflow, current status id), which distinguishes it from sibling candidate activity, attachment, and task listers. It does not explicitly use a verb like 'list' or name an alternative, but the GET endpoint and title make the action 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?

There is no when-to-use guidance or exclusion criteria. It does not tell the agent when to choose this over cats_list_pipelines, cats_filter_pipelines, or cats_get_pipeline_status_history, relying only on the candidate_id context.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds real context on top: pagination is one-page-at-a-time with a hard 100 cap, and the records contain personal data fields. It does not mention ordering, total counts, or rate limits, so it stops short of a 5.

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

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

Three short sentences, zero filler: scope first, then the returned fields, then pagination, then the sibling routing. Every clause carries information the agent can act on.

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

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

For a two-parameter read-only listing tool with annotations and full schema coverage, this is nearly complete — it even enumerates the returned fields in the absence of an output schema. Minor gap: no mention of next_page/total-count signaling in the reply, though the schema hints at it.

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

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

Schema coverage is 100%, so both `page` and `per_page` are already fully documented in the schema (including the next_page chaining hint). The description only restates the 100-per-page ceiling, which the schema already enforces via maximum: 100 — baseline 3.

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

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

States a specific verb+resource (list candidates) plus the shape of what is returned (name, emails, address, employer, skills, notes) and the underlying endpoint GET /candidates. It is clearly distinguishable from the get_* and search_* siblings at a glance.

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

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

Explicitly routes the agent away from this tool for targeted lookups: 'Use cats_search_candidates or cats_filter_candidates to find specific people.' That names both alternatives and the condition that selects them, leaving this tool as the browse-everything option.

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 safety is covered. The description adds only the endpoint path and candidate scoping; it does not mention pagination behavior, ordering, auth, or any other behavioral trait beyond what the structured fields 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?

The description is two short sentences with no wasted words and a front-loaded resource statement. It is efficient, though the endpoint restatement adds limited value beyond the tool name and 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 read-only list tool with full schema coverage and annotations, the description is minimally adequate: it says what is listed and the endpoint. However, it does not explain return values or usage context, which matters more because 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 all three parameters are documented in the input schema, including page, per_page, and candidate_id. The description adds no parameter semantics beyond the endpoint path, so the baseline of 3 is appropriate.

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

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

The description states the resource and scope precisely: tasks attached to a candidate, reinforced by the endpoint GET /candidates/{id}/tasks. It is clearly distinct from broader siblings like cats_list_tasks, though it does not explicitly use the verb 'list' and relies on the tool name/title for that.

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

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

There is no guidance on when to use this tool versus alternatives such as cats_list_tasks or cats_get_task, nor any stated prerequisites or exclusions. The context is only implied by the resource name and 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 and destructiveHint=false, so safety needs no restating. The description adds real value by naming the returned fields and flagging that results are paged, plus disclosing the underlying GET /companies call — only the absence of total-count/termination behavior keeps it from a 5.

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

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

One clause plus endpoint, zero waste, with the scope and payload fields front-loaded before the paging note. Nothing in it is redundant 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?

With no output schema, the description correctly compensates by listing the fields returned, and paging is covered with schema help. It is nearly sufficient for a simple two-param list tool; only pagination termination (what an empty next_page means) is left unstated.

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

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

Schema description coverage is 100%: page, its default, and the next_page chaining hint are all documented in the schema itself. The description's "paged" adds only a framing cue, not semantics beyond the structured fields, 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") with the returned fields enumerated (name, address, website, owner) and the backing endpoint noted. It does not distinguish itself from cats_search_companies or cats_get_company, so an agent must still infer when a list beats a search.

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?

"List ... paged" implies bulk enumeration rather than targeted lookup, and the schema's note about passing next_page reinforces the paging workflow. But no alternative (search_companies, get_company) is named and no condition for choosing among them 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds little beyond that: "paged" and the disclosure that results contain personal data are useful but not elaborated (no rate limits, no total-count behavior, no auth notes).

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 with the resource, payload hint and pagination note; no filler or repetition.

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

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

For a two-optional-parameter read-only list tool with no output schema, the description covers what is returned and that results are paged, which is enough to call it correctly. The only real gap is the missing routing guidance against search_contacts.

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 and per_page fully documented including defaults and the next_page chaining instruction, so the schema does the heavy lifting. The description's "paged" adds only a restatement; 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 client contacts") plus the fields returned (name, title, emails, company) and the underlying endpoint GET /contacts. It does not distinguish itself from the close siblings cats_search_contacts or cats_get_contact, so it stops short of a 5.

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

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

No statement of when to use this enumeration versus cats_search_contacts (which presumably filters) or cats_get_contact (single record). The word "paged" only hints at bulk enumeration; the agent must infer the choice from the sibling names.

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 contributes the useful extra facts that results are paged and the endpoint is a GET, but says nothing about default scoping (e.g. whether all pipeline entries or only active ones are returned) or ordering.

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 resource and its fields, then pagination, then the endpoint. Nothing is wasted, though the fragment style reads as note-taking rather than a sentence an agent can parse as a directive.

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

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

With no output schema, the description does the necessary work of naming the returned fields, and it flags pagination. For a simple read-only list tool this is close to sufficient; only the semantics of 'current status id' and any filtering behaviour are left 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%, with page, per_page and job_id each documented in the schema, including the next_page convention and the 1-100 range. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the work.

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

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

It names the specific resource (candidates in a job's pipeline) and enumerates the returned fields (pipeline id, candidate id, rating, status id), plus the underlying endpoint, so an agent can tell it apart from cats_list_candidate_pipelines or cats_get_pipeline by scope. The only gap is the telegraphic, verb-less phrasing, 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 guidance and no mention of alternatives, despite near-identical siblings such as cats_list_candidate_pipelines (pipelines of a candidate), cats_filter_pipelines, and cats_get_pipeline. Usage is only inferable from the described resource, which leaves the agent to guess which of the near-duplicate list tools 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 and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context: pagination behavior and the concrete field set returned (title, location, company, recruiter, status, workflow ids, dates), which matters because there is no output schema.

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

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

Three terse fragments with the resource and returned fields front-loaded and zero filler. 'GET /jobs' is slightly redundant but usefully anchors the tool to the underlying endpoint.

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

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

For a no-required-param list tool with full annotation coverage, the definition covers what is returned and that results are paged. The only real omission is routing guidance versus cats_search_jobs / cats_get_job, which is a selection rather than a completeness 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 both parameters (page, per_page) are fully documented with defaults, ranges and next_page chaining. The description's 'Paged' adds no syntax or semantics beyond what the schema already states, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (job orders) and enumerates the fields returned, so an agent knows exactly what it gets. It does not explicitly differentiate itself from the close siblings cats_search_jobs or cats_get_job, leaving that inference to the name.

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: 'List job orders' suggests browsing/unfiltered retrieval, which contrasts weakly with cats_search_jobs. There is no explicit when-to-use, no exclusion, and no pointer to the search sibling among the 30+ alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the reference endpoint (GET /jobs/statuses) and concrete example statuses, which is useful context, but says nothing about pagination behavior or result size 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?

Extremely short and front-loaded: the substantive content (what the statuses are) comes first. The trailing 'GET /jobs/statuses' is API-doc residue that adds little for an invoking agent but costs only a few tokens.

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

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

A simple, no-required-parameter, read-only list tool with no output schema; the description tells the agent what domain values come back (statuses) and gives examples, which is sufficient to call it correctly. Pagination is fully handled by 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 coverage is 100% — both page and per_page are fully documented in the schema, including defaults, ranges, and the next_page hint. The description adds nothing about 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 clearly that the tool returns the set of statuses a job order can have, and enumerates example values (Active, OnHold, Closed). The phrase 'job order' implicitly distinguishes it from the sibling cats_list_workflow_statuses, though the differentiation is not explicit.

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

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

No guidance on when to call this versus alternatives, no prerequisites, and no mention of the closely related cats_list_workflow_statuses tool. The agent must infer usage from the name and the enumeration alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile needs no restating. The description adds that results are paged and gives the underlying endpoint, but says nothing about ordering, default result volume, or how pagination terminates beyond what the schema's next_page note implies.

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: what is listed, what fields come back, and that it is paged. The trailing 'GET /pipelines' is mildly redundant but harmless. No wasted 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?

With no output schema, the field enumeration usefully covers the return shape, and the schema fully covers parameters. The gap is selection context: nothing here tells the agent when this unfiltered pipeline listing should be chosen over the candidate-scoped, job-scoped, or filtered pipeline 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%: both page and per_page have bounds, defaults, and usage guidance ('Pass the previous reply's next_page'). The description only echoes 'paged', which adds no semantics 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 candidate-to-job pipelines') and enumerates the returned fields (candidate id, job id, rating, workflow id, status id), so the agent knows exactly what data comes back. It does not distinguish this from the several sibling listers (cats_list_candidate_pipelines, cats_list_job_pipelines, cats_filter_pipelines), which keeps it below 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 named alternative. With four sibling pipeline tools in scope, the agent has to infer from the name alone whether this is the unfiltered, cross-candidate/cross-job listing or something narrower.

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 paged/GET /tasks context, but says nothing about result ordering, total counts, or the volume of data to expect from an open-world list call.

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 with the field list and pagination note packed in tightly; nothing is wasted. The parenthetical enumeration is dense but earns its place given there is no output schema.

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

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

With no output schema, the field enumeration is the only place the agent learns what a task record contains, and pagination is addressed. For a zero-required-parameter list tool this is close to sufficient; only ordering and scope hints are missing.

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

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

Schema description coverage is 100%, with both page and per_page fully documented including defaults, bounds, and the next_page chaining hint. The description only restates 'paged', so it adds no semantics beyond the schema – baseline 3 applies.

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

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

States a specific verb and resource ('List tasks') and enumerates the fields each task carries, so the agent knows both the operation and the payload shape. It doesn't explicitly name the sibling alternatives (cats_get_task for one task, cats_list_candidate_tasks for a candidate's tasks), but the list-vs-get distinction is unambiguous from the name.

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?

'paged' plus the schema's 'Pass the previous reply's next_page' implies the iterate-until-exhausted workflow. However, the description never says when to prefer this over cats_list_candidate_tasks or cats_filter_candidates, and gives no exclusion or scoping guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value by naming the endpoint (GET /users) and, with no output schema present, listing the fields that come back — information the agent would otherwise not have. It stops short of describing pagination behavior or whether results are scoped to a site.

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 zero filler: purpose and returned fields first, then usage, then the endpoint. Nothing repeats the annotations or 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 two-optional-parameter read tool, the description covers purpose, return fields (important since no output schema exists), and downstream use. The only gap is scope — whether the list is all users in the account or limited to a site/workspace — which would affect interpretation of the results.

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

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

Schema description coverage is 100%: page and per_page are fully documented, including the "pass the previous reply's next_page" chaining hint. The description mentions neither parameter, which is acceptable at full coverage but adds nothing beyond the schema 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 the CATS users (recruiters)") and enumerates the fields returned: id, name, title, access level. No sibling tool in the list targets users, so there is no ambiguity to resolve, and the parenthetical clarifies what a "user" means in this domain.

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

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

"Use the ids as owner or assignee" gives concrete downstream context that tells the agent why and when to call this tool. It does not spell out exclusions or contrast with alternatives, but no competing tool exists for this resource, so the guidance is adequate.

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 fully structured and the description needn't repeat it. The description adds modest context by identifying the underlying endpoint and clarifying the domain object's shape, but says nothing about pagination behavior or result ordering.

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 clauses with zero padding; the domain clarification comes first and the endpoint last. It is efficiently sized, though the raw endpoint reference earns its place only marginally.

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, optional-parameter list read with annotations covering safety and schema covering pagination, the description supplies enough to call it correctly. The only real omission is how it differs from closely-named siblings, which is a routing rather than completeness 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?

With schema description coverage at 100%, both pagination parameters are already fully documented in the schema, including the next_page chaining hint and per_page bounds. The description contributes nothing further about 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?

The description names the resource (pipeline workflows) and adds a concrete gloss — 'sets of statuses such as Contacted, Interviewing, Offered' — so an agent knows this returns workflow groupings rather than individual statuses. The listing verb is implied only by the tool name and endpoint rather than stated in prose, so it stops short of the best-in-class verb+resource statement.

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 guidance and no alternative is named, despite siblings like cats_list_workflow_statuses, cats_list_pipelines, and cats_list_job_pipelines that an agent could easily confuse with this one. The parenthetical definition of workflows hints at the distinction but never states the selection rule.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds context beyond the annotations: it names the underlying GET endpoint and lists the response fields (id, title, prerequisites, triggers), which matters because there is no output schema. It does not discuss pagination or rate limits, and the schema covers those, so this is not a 5.

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

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

Three short clauses with the core purpose first and the follow-up cue second; nothing is filler. The parenthetical field list is slightly compressed, but it still earns its place by compensating for the missing output schema.

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

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

For a simple read-only list tool, the description covers purpose, response shape, and the follow-up tool. With full schema coverage and clear annotations, nothing essential is absent, though a note on the pagination contract (next_page) would make it 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%, and the schema itself documents page, per_page, and workflow_id, so the baseline of 3 applies. The description only implies that one workflow is targeted; it adds no meaning to the paging parameters or to how workflow_id is chosen.

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 (statuses of one pipeline workflow) and enumerates the returned fields, so it is distinguishable from cats_list_workflows and cats_list_job_statuses. It never uses a clear verb like 'list/return', relying instead on a noun phrase plus the raw endpoint, which keeps it short of a 5.

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

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

It points the agent forward with 'Use the ids with cats_change_pipeline_status', which is a useful next-step cue. However, it gives no guidance on when to use this instead of cats_list_workflows or cats_list_job_statuses, and it states no prerequisites, such as needing a workflow id from cats_list_workflows. The usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety and scope are covered. The description adds that results are paged and the underlying endpoint, but says nothing about matching/ranking behavior, empty-result handling, or rate limits, so it adds only modest 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, zero filler, with the core operation stated first and the pagination note second. Nothing could be removed 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?

The tool is simple (3 fully documented params, no output schema, annotations covering safety) and the description covers the essentials plus pagination. It could still note ordering/relevance of results, but that is a minor gap for a search endpoint this straightforward.

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

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

Schema description coverage is 100%, so query, page and per_page are already fully documented in the schema, including the useful 'Pass the previous reply's next_page' hint. The description adds only the word 'paged' and the endpoint path, which is no real value beyond the structured fields.

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

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

States a specific verb+resource pair ('free-text search over candidates') and enumerates the searchable fields (name, email, skills, resume text), which clearly separates it from structured listing tools. It does not name the sibling it replaces, so an agent must infer the distinction from cats_filter_candidates and cats_list_candidates on its own.

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 'free-text search' implies usage versus the filter/list siblings, but there is no explicit when-to-use or when-not statement, and no guidance on choosing between this and cats_filter_candidates or cats_list_candidates. Usage 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds only that results are paged and the underlying endpoint path; it says nothing about match behavior (partial vs exact, which fields are searched), ordering, or empty-result 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 clipped sentences with the core purpose and pagination up front. The raw endpoint path adds little 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 three-parameter read tool with no output schema and full annotations, this is minimally sufficient to call it correctly. However, an agent still cannot tell what a result contains (IDs? names? which company fields) or how relevance ordering works.

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 explains page/per_page defaults, ranges, and the 'pass the previous next_page' convention. The description's '?query=' merely restates the required parameter and adds no semantics such as minimum length or matching rules.

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 ('free-text search over companies') and notes it is paged, which distinguishes it from a plain list operation. It never names cats_list_companies or cats_get_company directly, so the distinction from siblings must be inferred from the word 'search'.

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: 'free-text search' signals you should call this when you have text rather than browsing. There is no explicit when-to-use/when-not guidance and no pointer to cats_list_companies for enumeration or cats_get_company for a known 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that results are paged and the underlying endpoint, with no mention of result ordering, matching semantics, 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 short sentences, front-loaded with purpose. The raw endpoint string is of marginal use to an agent and is arguably unnecessary filler, but the definition is otherwise waste-free.

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 could reasonably say what a result contains (contact fields, next_page handling) — it only hints at paging. Adequate to invoke correctly, but thin for an agent deciding how 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 description coverage is 100%, documenting query, page and per_page fully, so baseline is 3. The description adds nothing beyond echoing the 'query' parameter name in the endpoint string, and certainly no syntax guidance for the free-text term.

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 ('Free-text search over client contacts') plus the paging behavior, which clearly distinguishes it from the sibling list_contacts / filter-style tools. It does not name a sibling explicitly, so it stops short of a 5.

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

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

The word 'search' implies it is for text queries rather than full listing, but the description never states when to use this over cats_list_contacts or what happens with unmatched terms. No exclusions or alternative routing 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only that results are paged and the HTTP route, without saying what fields are matched or how many results a query typically 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?

One compact sentence with the core scope front-loaded and no filler. The trailing endpoint fragment earns little 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?

Annotations carry the safety profile, the schema carries all three parameters with defaults and pagination linkage via next_page, and no output schema exists to explain. For a simple paged search tool, nothing essential is missing.

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

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

Schema description coverage is 100%, so page, per_page, and query are all documented with defaults and bounds in the schema itself. The description adds no meaning beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ("Free-text search over job orders") plus paging, which separates it from cats_list_jobs at a glance. It stops short of naming the sibling it substitutes for, so the differentiation is implied by the word "free-text" rather than explicit.

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

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

There is no guidance on when to reach for this instead of cats_list_jobs, cats_get_job, or cats_filter_candidates. The only usage signal is the endpoint string and the word "paged," which leaves the agent to infer that free-text matching is the selection criterion.

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