HireHop MCP by usefulapi

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 genuinely new context: it is served by the authenticated current-user endpoint (auth requirement) and deliberately excludes account settings and credentials (scope boundary). It does not discuss failure modes when unauthenticated, but the annotations carry most of that weight.

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 first front-loads the returned fields, the second adds endpoint and scope context. There is no repetition of the title and 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 zero-parameter read tool with no output schema, the description compensates by enumerating the exact fields returned and clarifying what is not included. Nothing an agent needs in order to call it correctly is missing.

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

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

The schema has zero parameters, which is the baseline-4 case per the rubric. The description correctly adds no parameter guidance because none is needed, and instead spends its words on the returned field set.

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 (show the connected user) and enumerates the exact fields returned (ID, company ID, name, email, default depot), so an agent knows precisely what it gets. It is unambiguously distinct from siblings like hirehop_get_job or hirehop_list_contacts, which operate on different resources.

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 'connected / authenticated current-user' framing makes the use case clear (identify the caller), and 'excludes account settings and credentials' draws a useful scope boundary. It stops short of naming a sibling alternative or stating when-not to call it, so it lands just below the explicit when/alternatives bar.

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

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

Annotations already cover readOnly/openWorld/destructive=false, so the bar is lower. The description adds value beyond that: the underlying endpoint (GET /api/job_data.php), the shape of the return (customer, dates, status) and the crucial caveat 'details available to your user', which alerts the agent to permission-scoped results. This is meaningful behavioral 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 compact clauses, front-loaded with the verb, resource and input source. The API endpoint reference is the only arguably extraneous element, but it contributes to transparency rather than bloat.

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-param read tool with rich annotations and no output schema, the description covers the input origin, the endpoint, and the general return contents. Nothing critical is missing, though a note on error behavior for invalid IDs would round it out.

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 0%, but the description compensates well for the single param: it specifies the type ('numeric'), its meaning ('job ID') and its source (from hirehop_search_jobs). That is essentially all an agent needs to supply job_id correctly.

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 (read), resource (one rental job's details) and the key (numeric job ID). It clearly distinguishes itself from hirehop_search_jobs, which supplies the ID, so an agent can route between them without opening either schema.

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

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

The description implies the workflow ('job ID from hirehop_search_jobs') and thus gives context for where the input comes from. But it doesn't state when to prefer this over a sibling retrieval tool (e.g., search_jobs or get_project) or any preconditions, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the underlying endpoint (GET /php_functions/project_get_data.php), which is mild context but doesn't disclose return shape, error behavior, or permission requirements. Useful but not rich.

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, no wasted words, with the returned-fields summary front-loaded before the ID sourcing instruction.

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

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

A single-parameter read tool with annotations covering safety; the description even enumerates what comes back (details, customer, managers, dates, status) in the absence of an output schema. Missing only minor detail like pagination or error cases, which are unlikely to apply 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 0%, so the description needs to carry the load — and it does: it tells the agent the parameter is a numeric project ID obtained from hirehop_search_jobs. It doesn't add format/validation detail (e.g., 1-based integer), but the essential meaning is supplied.

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 ('Read') plus resource ('a project's details') and an enumeration of the returned facets: customer, managers, dates and status. It implicitly differentiates from siblings like hirehop_get_job by naming hirehop_search_jobs as the source of the project ID, though it doesn't explicitly contrast with get_job.

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 prerequisite clearly: 'Use its numeric project ID from hirehop_search_jobs', which gives the agent a workflow (search first, then get). No explicit when-not or alternative routing beyond that one reference.

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 readOnly/openWorld/non-destructive, so the description adds real value: exactly one page is returned, paging totals are supplied, and hidden or deleted contacts are filtered out. The raw endpoint is included, which helps confirm the underlying behavior, though nothing is said about auth or rate constraints.

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

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

Four short sentences, front-loaded with the core purpose, then scope, then filtering behavior. Every sentence carries information and nothing is padded.

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

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

With eight parameters, no output schema and zero schema coverage, the description should explain at least the filter fields and paging semantics. It covers the population scope and pagination limit but leaves half the call contract undocumented.

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 0%, so the description carries the full burden, yet it only implicitly names the enum values ('customer, delivery-address and supplier'). The name, email, company, telephone, company_id, page and rows filters are never explained, leaving an agent to guess at matching semantics.

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 ('Read or search ... contacts') and names the three contact categories that map to the `list` enum. It is clearly distinguishable from siblings like list_products or search_jobs, though it never explicitly contrasts itself with 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?

'Read or search' implies the tool supports both browsing and filtered lookup, but there is no explicit statement of when to use it versus anything else, nor any exclusion conditions. The usage mode is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine value by disclosing the shape of the result (IDs, names, virtual flag) and the backing endpoint, which an agent cannot get from annotations or from a missing output schema. It omits any statement about result size, ordering, or whether the list is cached/live.

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

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

Two short sentences, front-loaded with what the tool returns. The trailing endpoint path ('GET /php_functions/get_depots.php') is of marginal value to an agent selecting or invoking the tool, making it the one element that does not fully earn its place.

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

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

For a zero-parameter read-only listing with no output schema, the description covers purpose and result shape, which is what an agent needs to select and call it correctly. The absence of result-volume or ordering notes is a minor gap given the tool's simplicity.

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 no parameters at all, which is the baseline-4 case; there is nothing for the description to disambiguate. The single 'virtual' flag mentioned is a returned field, not an input, so no parameter semantics are missing.

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

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

The description gives a specific verb ('List') and resource ('depots'), plus the exact fields returned (IDs, names, virtual flag), so an agent can distinguish it from siblings like hirehop_list_contacts or hirehop_list_products by resource alone. It stops short of explicitly contrasting itself with any sibling, but none of the listed siblings compete for the same resource.

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

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

Usage is only implied: it is a depots listing, so an agent infers 'call this when you need depot identifiers or names.' There is no statement of prerequisites, no pagination/filtering guidance, and no when-not condition, though with zero parameters and no competing sibling the practical ambiguity is low.

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 mark the tool read-only and non-destructive; the description adds that notes can contain HTML and reinforces that it never creates or changes notes. It does not cover auth or rate limits, but the added HTML warning is useful context beyond annotations.

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

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

The description is three short sentences with the core purpose front-loaded and no wasted text. The exclusion and HTML warning are both material and efficiently stated.

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 description identifies the returned resource and notes that content may be HTML, but it does not describe the response shape or pagination behavior for a list endpoint. With no output schema and partial parameter explanation, some details are left to inference.

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

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

Schema description coverage is 0%, and the description only partially compensates: it explains record_type through the supported record categories and implies page via 'a page of notes.' It does not explain rows or record_id semantics, leaving half the parameters undocumented.

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

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

The description gives a specific verb (Read) and resource (notes), lists the exact record types the notes can belong to, and excludes sales inventory notes. This makes the tool's scope distinguishable from the job/project/product reading 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?

It clearly states the applicable record types and explicitly excludes sales inventory notes, giving useful when-to-use context. It does not name alternatives, but no sibling notes tool exists in the provided set.

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 two things beyond that: results are paginated ('One page') and include vendor totals, plus the important semantic that no availability/booking state is computed. It says nothing about auth or rate limits, but for a read-only catalog listing that is a minor gap.

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

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

Three short sentences, front-loaded with what the tool returns and immediately followed by the key scope caveat. The trailing endpoint path (GET /modules/stock/asset_assign_list.php) is the one element of questionable value for an agent, but it is compact.

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

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

With no output schema, the description usefully substitutes by naming the returned fields, and annotations cover the read-only safety profile. What is missing is the input side: nothing tells an agent how paging, page size or category filtering behave, which is the main thing needed to call this correctly with four undocumented parameters.

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 0%, so the description must carry parameter meaning, and it does not. The four parameters (kind, page, rows, category_ids) are never explained, and the non-obvious constraints on rows (minimum 20, maximum 100) and category_ids (max 30 items) go unmentioned. Only 'rental products or tracked sales products' loosely gestures at the kind enum, and the listed fields are return values, not inputs.

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

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

States a specific verb and resource ('List rental products or tracked sales products') and enumerates the fields returned (categories, IDs, names, part numbers, status). It also preempts a likely misinterpretation by declaring 'This is a catalog, not a date-specific availability report', which is more differentiation than the unrelated sibling tools require.

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 'catalog, not a date-specific availability report' line gives an explicit when-not condition, which is the main routing decision an agent faces here. It stops short of naming an alternative tool to use for availability questions, so the exclusion is stated without a redirect.

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 genuinely useful behavior beyond that: results are paginated one page at a time and include vendor totals. It says nothing about page-size limits, ordering defaults, or error behavior.

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

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

Two short sentences with the core scope front-loaded, followed by the pagination caveat. The raw endpoint path is of marginal value to an agent but is compact and not distracting.

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 5 undocumented parameters, no output schema, and a paginated result set, the description should explain ordering, page size, and how 'vendor totals' are shaped in the response. It mentions only paging in passing, leaving most calling decisions to guesswork from bare schema constraints.

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 0% across 5 parameters, so the description carries the full burden and largely fails it. 'Page' and 'subsequent pages' hints at pagination, but rows, sort_by, sort_direction and even project_id are never explained; the enums and min/max ranges in the schema have no narrative counterpart.

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 a single page of the jobs in a project') plus what the payload includes ('with vendor totals'). An agent can distinguish it from hirehop_get_job (one job) and hirehop_search_jobs (cross-project search), though neither sibling is named.

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 subsequent pages for the full project' tells the agent this is one page of a larger set, which is useful. But there is no explicit when-to-use vs hirehop_get_project or hirehop_search_jobs, and no preconditions or exclusions.

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

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

The annotations already establish that this is a safe read-only search. The description adds useful behavioral context beyond that: it returns one page plus vendor totals, pages must be followed for a complete report, and dates use depot-local calendar dates.

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 four tight sentences with no filler. Key scope and behavior are front-loaded, and each sentence contributes useful information about filtering, pagination, or date interpretation.

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 15-parameter search tool with no parameter descriptions and no output schema, the description is minimum viable: it conveys the main purpose, some key filters, pagination behavior, and date semantics. It is incomplete for fully exploiting all parameters, especially sorting, mine_only, and the project-inclusion toggles.

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 0%, so the description must carry parameter documentation. It explains the main filter categories, the late-return/money-owed/needs-invoice booleans, one-page pagination, and depot-local dates, but it leaves sort_by, sort_direction, mine_only, include_jobs, include_open_projects, and include_closed_projects unexplained.

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: searching rental jobs and open/closed projects, with named filter categories. It is clearly distinct in practice from sibling retrieval tools like hirehop_get_job and hirehop_get_project, but it does not explicitly differentiate itself from them.

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

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

Usage is implied through the filter examples (late returns, money owing, jobs needing an invoice), giving the agent reasonable cues for when this search tool is appropriate. However, it does not explicitly say when to use this instead of hirehop_get_job, hirehop_get_project, or hirehop_list_project_jobs.

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