MCP Tools Reference

Six tools, all reads. You do not call these yourself — the AI client does — but knowing what exists explains what a client can and cannot answer.

---

list_projects

Every workspace and project the credential can reach, with its role in each.

The starting point. Nothing else is useful until the client knows which workspace and project to name, and it will usually call this first without being asked.

---

describe_project_data

What can be queried in one project: the entities, their fields, the values those fields actually hold, the operators available, and the named cross-entity conditions.

It also carries this project’s row limits and a short set of usage notes — the rules a client needs before writing its first query.

This is per-project, because custom fields are. A client reads it before writing a query so that it uses your vocabulary rather than guessing.

Only the entities the credential may read are listed. If your role cannot see defects, a connected client is never told that defect fields exist.

A full catalog runs to around a hundred kilobytes on a real project, so a client whose context cannot hold that can ask for a compact one instead: every entity, field, operator, predicate and description is kept, and only the lists of example values are sampled.

---

query_records

Runs a structured query and returns matching rows, a count, or counts per group.

This is the one that does the work. It covers test cases, requirements, tasks, defects, releases, test runs, run results, labels, shared steps, parameters and custom fields, with filters, time windows, sorting, and cross-entity conditions such as never executed, has open defects, in this release, is flaky and covered.

It can also answer how many per what — failures per requirement, defects by severity, cases by folder — as counts per group rather than a list to tally. A record linked to several things counts for each of them, which is what a question like “failures per requirement” means.

That means questions like these are a single query rather than several:

• Test cases in release 4.2 that failed and have an open defect
• Requirements with no test coverage
• Defects raised in the last 30 days, unassigned, ordered by severity

Every answer comes with an explanation of how the query was read, so a client can tell you what it actually asked.

The client is also told how to write a query — that dates are relative rather than calculated, that names are resolved server-side so an invented id is not needed, and which of this project’s fields are worked out on demand. Those are the mistakes that would otherwise return a plausible-looking answer instead of an error.

Bounded on purpose

A query returns at most 500 rows per page, and one that would have to scan too much is refused with a note saying so rather than run. A single answer is also capped at 512 KB — an oversized one is refused, never truncated, because half a table read confidently is worse than no answer. Narrow it with a filter or a shorter time window.

Every answer reports how many records matched in total, not how many were returned — so a client is never left to infer the size of a set from the size of a page. When rows are left over it is also given a continuation, and can keep asking until there are none.

Continuing is tied to the exact question it started from: change a filter and the client has to start again rather than stitch two different result sets together. If the data changes underneath a client mid-way, it is told so and starts again, rather than being handed a page that quietly repeats or skips rows.

Paging is the fallback, not the plan

Reading thousands of records into an AI’s context rarely answers a question better than a narrower query does — and a client is told as much. For “how many”, asking for a count is one call instead of twenty.

---

get_record

One whole record by its human code — a test case (CHK-123), requirement (REQ-12), defect (DEF-4), release, or test suite.

query_records returns only the columns a query asked for. This returns everything, and is what a client uses once it has found the row that matters.

---

get_execution_history

Executions of one test case, newest first — the run, the result, who ran it and when. Fifty at a time by default, and a client can ask for up to two hundred.

Answers “has this ever passed?” and “when did this start failing?”, which a query over current state cannot.

---

get_release_readiness

Everything a sign-off needs, in one call: the Go/No-Go verdict and the reasons behind it, the score and its dimensions, every acceptance gate with its target, execution progress, requirement coverage, defect health, the outstanding work — and every failing test case joined to the requirements it traces to and the defects raised against it.

The same calculation the Release Readiness dashboard runs — but reported in full: the dashboard’s own page leaves out the worklist and the reasons, and this does not. The reasons are the engine’s own, so a client reports why a release is blocked rather than inferring a story from the numbers.

Results are not test cases

A parameterised case has one result row per dataset, and a case can fail in several executions — so the answer reports failing rows and failing cases as two separate numbers. A client is told to say which it means.

For a completed or archived release this returns the frozen sign-off snapshot rather than live numbers — a sign-off figure that moved after sign-off would not be a sign-off. It is flagged as a snapshot, with the date it was taken, so a client can tell you which it is looking at.

If the credential cannot read defects, the assessment still comes back — without defect health, and saying so. It does not quietly report a release as clear of blockers it was never allowed to look for.

---

What Is Not Here

No tool creates, edits, deletes, executes or imports anything.

There is also no access to Canon documents, the Hawzu documentation, or chart generation. Those are Hawzu features, not MCP ones.

---

Refusals

When a credential may not read something, the tool says so. It does not return an empty result.

That distinction matters more than it looks: an empty list is indistinguishable from a correct answer of “none”, and an AI told “no rows” will report that there are no open defects when the truth is that it was not allowed to check.