Rillsoft Project MCP server

Official

by rillsoft

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

List candidates

rillsoft_task_resource_candidate_list

Read-onlyIdempotent

Reports per task the roles and matching employee/machine candidates with free capacity, cost, and conflicts to guide resource assignment.

Instructions

Reports per task the roles attached to it (quantity, assigned, balance, balanceOpen) and the candidates matching them - the same set the task dialog shows after the role and team filter. Per candidate: id, name, code, teamId, free (free capacity within the task period), cost, alreadyAssigned, scheduleConflict and reason where it cannot be assigned; with type employee also availability and efficiency. Read-only, no undo step. Filling the slots afterwards goes through rillsoft_task_employee_assignment_set, rillsoft_task_machine_assignment_set or rillsoft_task_resource_assignment_fill.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`type`	No	resource type; employee by default. Here resource covers exactly these two - an assistant works on concrete people and machines. The other four resource types (role, team, material, machine_role) are read and written through rillsoft_resource_usage_list and rillsoft_resource_usage_set	employee
`roleIds`	No	ids of the roles or machine roles to filter on; empty means every one attached to the task. On opening, the task dialog ticks the first role only - to reproduce exactly its list, pass that id explicitly
`taskUuid`	No	UUID of one task; taskUuids is the alternative
`taskUuids`	No	UUIDs of several tasks; leave both empty for every task of the visible project or subproject
`searchText`	No	filter by name, like the search field of the dialog
`teamFilter`	No	narrow further to the team of the task or of its subproject; omit it to get the preset of the dialog (on as soon as a team is carried)
`matchingOnly`	No	true (the default) = only resources that carry one of the roles; false = the unfiltered master data, as with the role tick cleared

Output Schema

TableJSON Schema

Name	Required	Description	Default
`type`	Yes	resource type
`tasks`	Yes	the tasks evaluated

Schema Changelog

Changes observed during successful MCP inspections.

First observedv10.0.626Oct 17, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered; the description reinforces it with 'Read-only, no undo step.' Beyond that it discloses meaningful behavioral detail: what each candidate carries (free capacity within the task period, cost, alreadyAssigned, scheduleConflict and reason), and that employee-type candidates additionally carry availability and efficiency. That is real added context, though it overlaps with the 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.

Conciseness4/5

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

Front-loaded with the core purpose, then structured detail on the returned fields, then the routing sentence to the assignment tools. The 'Read-only, no undo step' clause slightly duplicates the annotations, but overall every sentence carries content and nothing is padding.

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

Completeness5/5

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

For a read-only list tool with 7 optional params, a rich input schema and an output schema, the description covers purpose, default/dialog semantics, candidate field meanings, and the follow-up write path. An agent has everything it needs to select and call it correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so each of the 7 parameters is already documented, including the default-preset behavior of roleIds, teamFilter and matchingOnly. The description adds only a holistic framing - that the result reproduces the dialog's filtered candidate list - rather than per-parameter semantics. Baseline 3 is correct when the schema does the heavy lifting.

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

Purpose5/5

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

The description states a specific verb and resource - it reports, per task, the roles attached and the candidate resources matching them - and pins the scope to the exact set the task dialog shows after the role/team filter. It is immediately distinguishable from siblings like rillsoft_task_role_assignment_derive and the assignment_set family, which it names.

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

Usage Guidelines4/5

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

Usage context is clear: this is the read/list side, and filling the slots afterwards goes through rillsoft_task_employee_assignment_set, rillsoft_task_machine_assignment_set or rillsoft_task_resource_assignment_fill. That routes the agent to the correct follow-up tools. It does not explicitly state when NOT to use it or contrast with the other list-style siblings (e.g. resource_usage_list), so it stops short of a 5.

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

Deploy Server