The QC Database MCP Server lets an AI assistant perform construction quality control (QC) database work on your behalf, connecting to QCDatabase.AI using your own authenticated session. Here's what it can do:
Authentication & Session Management
Sign in/out via browser-based OAuth, check auth status, and list organizations/tenants.
Project Navigation
List, search, and set the active project; view project members, controlled-vocabulary lists (welders, materials, pipe sizes, etc.), map item schemas, and document folders.
Document & Drawing Management
Upload MTRs, NDE reports, certificates, and other documents; retrieve AI-extracted data or write custom extraction results back; upload isometric PDFs (auto-split into sheets) and large-format drawings (P&IDs, plans).
Map Items (Welds, Flanges, Fittings)
List, create, and manage map items with schema-defined fields; mark items complete or accepted with user-accountable sign-offs; attach photos with captions.
Fillable PDF Forms
Browse, preview, download blank templates (RIRs, inspection checklists), and submit completed forms back as documents.
Inspection Forms & Notes
Create, list, and complete inspection form submissions; create, list, and resolve project notes with severity and assignments.
Inspection & Test Plans (ITP)
List ITP line items and mark them complete or accepted with sign-offs.
Quality Holds (Locks)
Add, unlock, assign, or delete quality hold points on map items or ITP line items to block turnover until resolved.
Turnover Package Management
List and create reference requests (open punch-list items needing proof); list and create references linking source items to proof documents; generate a turnover report tracking completion progress.
Semantic Search & User Manual
Perform natural-language meaning-based searches across project data; search or browse the QC Database user manual.
Utilities
Generate QR codes.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@QC Database MCP Server Upload this MTR to Mill Test Reports"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WARNING! Our apologies, but some of the modifications we made to allow remote hosting of this MCP server have broken the stdio tools. We are working on a fix ASAP. Please check back here later.
A small program that lets an AI assistant (like Claude) do your everyday QC Database work for you — set the project you're working on, upload records, read what the AI pulled off a document, and find and close out the items still needed for a complete, traceable turnover package.
It runs on your own computer. Your AI assistant talks to it; it talks to QCDatabase.AI on your behalf, using your own login.
Built on the official Model Context Protocol
Python library and the QC Database MCP specification — published at
qcdatabase.ai/mcp_server_spec.md and
kept in this repo as mcp_server_spec.md.
Once it's connected, you can talk to it in plain language. For example:
"Connect to QC Database." → signs you in (opens your browser once).
"Work on the Riverside Unit 2 project." → pins that project for the session.
"Upload this MTR to the Mill Test Reports folder."
"What's still missing for turnover on this project?"
"Show me the open reference requests assigned to me."
"Find welds that failed X-ray near line 12." → meaning-based (semantic) search across your project data, ranked by relevance.
"How do I create a test package in QC Database?" → answers from the built-in QC Database user manual, so you can learn the app without leaving your assistant.
"Attach this photo to that weld."
"Mark this inspection complete." (it will remind you that the sign-off is recorded under your name — that's your call, not the AI's).
Related MCP server: JoeMCP
You need Python 3.10 or newer on your computer.
Windows: install from the Microsoft Store (search "Python") or from python.org/downloads. During the python.org install, tick "Add Python to PATH."
Mac: brew install python or get it from
python.org/downloads.
To check it's installed, open a terminal (PowerShell on Windows, Terminal on Mac) and run:
python --versionYou should see Python 3.10 or higher. (On some Macs the command is python3.)
From a terminal, in this folder:
pip install .That's it. This installs the server and a command called qcdatabase-mcp.
If
pipisn't found, trypython -m pip install .(orpython3 -m pip install .).
Claude Desktop launches this server for you and shows its tools in your chats. Set it up once:
If you don't have it, download it from claude.ai/download and sign in.
In Claude Desktop:
Open Settings (Windows: menu ☰ → File → Settings; Mac: Claude → Settings).
Go to the Developer tab.
Click Edit Config.
This opens (and, if needed, creates) a file named claude_desktop_config.json.
You can also open it directly:
Windows: %APPDATA%\Claude\claude_desktop_config.json
Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Put this in the file. If the file already has other servers, just add the
"qcdatabase" block inside the existing "mcpServers" section.
Windows:
{
"mcpServers": {
"qcdatabase": {
"command": "python",
"args": ["-m", "qcdatabase_mcp"]
}
}
}Mac (Python is usually python3 there):
{
"mcpServers": {
"qcdatabase": {
"command": "python3",
"args": ["-m", "qcdatabase_mcp"]
}
}
}Save the file.
If Claude can't start it (you see "python not found" or the server fails), use the full path to Python instead of just
"python". Find it by runningwhere python(Windows) orwhich python3(Mac) in a terminal, then paste that path as the"command". For example on Windows:{ "mcpServers": { "qcdatabase": { "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python312\\python.exe", "args": ["-m", "qcdatabase_mcp"] } } }(Use double backslashes
\\in Windows paths inside JSON.)
Fully quit and reopen the app (on Windows, also close it from the system tray; on Mac, Quit with Cmd-Q — closing the window isn't enough). The new server only loads on a fresh start.
Start a new chat and look for the tools/connector indicator (a slider or tool icon near the message box). Click it and you should see qcdatabase with its tools listed. If you don't, see Troubleshooting.
Then ask Claude to "connect to QC Database" to sign in — see below.
Sign in. Ask the assistant to connect to QC Database (the login
tool). Your web browser opens; log in and pick which company workspace
you want to connect. That choice locks the connection to that one
organization. You only do this once — it's remembered.
Pick your project. Ask it to work on a project by name, or list your projects first. Almost every action happens "inside" a project, so the server asks you to choose one before it will do project work. You can switch projects any time.
Get to work. Upload documents and drawings, check what's missing for turnover, create and close reference requests, add notes and photos, and so on.
Session: login, logout, auth_status, whoami
Find your way around: list_tenants, list_projects, set_project,
get_active_project, list_project_members, list_lists, list_list_items,
list_map_item_schemas, get_map_item_schema, list_document_folders,
list_form_schemas
Controlled-vocabulary lists: create_list_item, update_list_item,
delete_list_item (a soft delete — the entry stops appearing in list reads but
stays on record)
Jobs & packages: list_jobs, create_job, list_packages,
create_package, list_line_specs, create_line_spec
Upload records: upload_document, upload_document_version,
download_document, upload_drawing, upload_large_format_drawing,
upload_drawing_to_package, upload_drawing_version,
upload_large_format_drawing_version, attach_photo
Drawings: list_drawings, get_drawing (incl. pixel width/height — the
HTML5-canvas coordinate space for map items), export_drawing,
export_large_format_drawing
Fillable PDF forms: list_fillable_templates, get_fillable_template,
download_fillable_template, submit_fillable_template
Structured data: get_document, set_document_extracted_data,
list_documents, list_map_items, get_map_item, create_map_item
(place welds/flanges by pixel coordinates), bulk_create_map_items,
bulk_update_map_items (batch up to 500 items on one drawing/schema). Always
call list_map_item_schemas first — see the CAD/PCF/.weldb note below
Zipmaps (a whole mapped drawing in one upload): inspect_zipmap,
upload_zipmap — see Zipmaps
Repairs: list_repair_codes, add_map_item_repair
Inspection forms & notes: list_form_submissions, create_form_submission,
get_form_submission, update_form_submission, complete_form_submission,
create_note, list_notes, resolve_note
Photos: list_photos, attach_photo
ITP & sign-offs (your call): list_itp_line_items, get_itp_line_item,
create_itp_line_item, update_itp_line_item, mark_map_item_complete,
mark_map_item_accepted, mark_itp_complete, mark_itp_accepted
Quality-hold locks (witness/hold points — the user's call): list_lock_types
(read only), list_locks, get_lock, add_lock (place a hold point — fit-up,
tack-up, weld-cleanliness, FME, final-closure, boiler-tube FME sponge-in/sponge-out,
etc. — on a map item or ITP line item so it can't be turned in until inspected),
unlock_lock, assign_lock, delete_lock (withdraws a hold placed in error — a
soft delete: kept in the audit trail, no longer holding the item; use unlock_lock
for a hold that was actually satisfied). A lock is a construction quality gate,
not a security control; place or clear one only at the explicit request of its
owner/author or an authorized inspector. Creating or editing lock types (the
named hold definitions, and who may place/clear each) is intentionally not
exposed here — that permission-sensitive setup is done in the web app's Project
Admin, and the assistant will point you there
Turnover (the important part): list_reference_requests,
create_reference_request, list_references, create_reference,
turnover_report
Receiving: list_shippers, list_shipper_line_items
Semantic search (meaning-based, ranked): semantic_search — natural-language
search across the project's documents, drawings, large-format drawings, jobs,
packages, list items, map items, form submissions, notes, and shippers
How QC Database works: search_user_manual (ask "how do I…?" questions and
read the product help articles), list_user_manual (browse the help contents)
Utilities: generate_qr_code
This server is a natural partner to the systems that already describe your geometry — CAD/CAE exports, PCF piping files, and .weldb boilermaker replacement-panel files. Those sources carry most of what a good map item needs, so the assistant can turn them into accurate weld maps — if it follows two habits:
Fetch the schema first. Always call list_map_item_schemas before
create_map_item / bulk_create_map_items. That picks the right schema and
reveals its exact fields, so source values land where they belong instead of
being guessed or free-texted:
PCF (piping) files carry most of what a pipe weld needs — joint type, material, weight/sch.
.weldb files carry material, tube wall thickness, and the weld's rectangular position on the drawing — enough to build a weld map automatically.
Match the source's geometry — point vs. rectangular welds. This is the big
data-quality lever. A PCF pipe weld is a single point weld (one x/y). A
.weldb weld has a rectangular position — give the second point
(x_position_2/y_position_2) as the opposite corner so the extent is
preserved. Collapsing a rectangular weld to a bare point (or spreading a point
weld into a box) silently corrupts the map. Fetching the schema up front is
what makes this distinction obvious before any items are placed.
A zipmap is a plain zip that packages one drawing (a PNG, optionally the source single-page PDF) together with every map item already placed on it and the JSON Schemas that describe those item types. It is the "bring your own AI" hand-off: your model, CAD export, or takeoff tool produces the map; QC Database ingests it.
upload_zipmap replaces the old three-step dance (upload the drawing → wait →
bulk-create items against it) with one transactional request. The drawing, all
of its map items across every schema, and its extracted data are created together
— or nothing is. No server-side AI runs on it; the map is yours.
Ask for it in plain language: "upload this zipmap into the Unit 2 hydro package." Behind that, the assistant does three things first:
inspect_zipmap — looks inside without uploading: the drawing size, how
many items of each type, the data fields those items use, and which types are
not yet bound to a QC Database map item schema.
list_map_item_schemas / get_map_item_schema — a zipmap names its types
locally (weld, heat); QC Database identifies schemas by id. Any unbound type
must be paired with the schema it belongs on (schema_ids={"weld": "<id>"}),
and comparing the type's fields against the schema's fields is how that match is
confirmed. Producers can skip this by writing the id into the archive's
schemata/<type>.schema.json up front.
list_packages — the new drawing has to be filed somewhere, and the API
requires a package id. Pick (or create_package) the scope package first.
Coordinates travel as pixels of the zipmap's PNG (top-left origin, y down) — exactly the space QC Database maps in — so nothing is rescaled or flipped. If the project uses per-schema auto-numbering, its labels win over the zipmap's item ids and the result reports each new item against the id it came from.
Re-sending a corrected map? mode="replace" first soft-deletes any live
drawing in that package with the same drawing number (retained in the audit trail,
gone from drawing lists, and its map items go with it) instead of leaving a
duplicate. The default, mode="append", always creates a new drawing.
Everything that can be checked locally is checked before the upload — a missing PNG, a type with no schema id, a coordinate outside the drawing, PDF-space coordinates that would misplace every item — so a bad map fails in a second with a list of what to fix, not after a multi-megabyte round trip.
Zipmaps are read from your own computer, so this works with the local (stdio) server. A hosted server never touches your disk (see Filesystem safety).
Marking work complete or accepted is a buy-off — the system records it under your name and the current time. The assistant can do these for you, but every one of those tools tells you plainly that you are responsible for the action. The server never signs anything off silently. Treat those as your decisions, made with your go-ahead.
The server runs locally and only talks to https://qcdatabase.ai.
Your login is pinned to one organization (chosen at sign-in) and your session is pinned to one project — so the assistant can't reach into a different workspace or project by accident.
The server only requests the permissions an everyday user needs; admin actions are out of scope by design.
You can disconnect any connected app at any time from your QC Database account.
Your login is stored on your own computer in a per-user folder:
Windows: %LOCALAPPDATA%\qcdatabase-mcp\store.json
Mac: ~/Library/Application Support/qcdatabase-mcp/store.json
Linux: ~/.config/qcdatabase-mcp/store.json
Run the logout tool (or delete that file) to forget the login.
This is a hard rule the server must always uphold — for its own safety and for anyone contributing to this open-source repo:
The server never modifies its own files. No tool can read from or write to
the server's whole installation — its own source, its dependencies
(site-packages), the virtualenv, or (from a checkout) the repo root — whatever
path it is given, so the assistant can never edit the server's or a
dependency's code (no self-modification). Downloads also refuse to overwrite
an existing file; choose a new path.
The server never touches its credential store beyond the token flow. No
tool can read or write the per-user config directory, so a token can never be
exfiltrated or overwritten through a tool, and it can never be committed to the
repo (it lives outside any checkout; store.json is also .gitignored).
The only local files a tool ever touches are the user's own documents, and only in stdio mode — the upload tools read a file you point them at, and the download/export tools write to a path you choose. In hosted mode the server refuses all local filesystem access, because the disk is the server's, not yours (uploads/downloads there would need a client-side file channel instead).
These rules are enforced in code by _guard_local_path in server.py.
"qcdatabase" doesn't show up in Claude Desktop after restarting.
Make sure you fully quit the app (system tray on Windows, Cmd-Q on Mac) and reopened it.
Check the config file is valid JSON — a missing comma or brace stops every server from loading. Paste it into a JSON checker if unsure.
If it still doesn't load, set "command" to the full path to Python (see
the install note above).
Look at the Claude Desktop logs for an error: Windows
%APPDATA%\Claude\logs\, Mac ~/Library/Logs/Claude/.
"Not logged in." Ask the assistant to connect to QC Database and finish the sign-in in your browser.
"No project is set." Ask it to work on a project, or to list projects.
A newer feature says "Access denied (403)" (e.g. the user manual, or the
quality-hold locks). If you first signed in with an older version, your saved
app registration predates that feature's permission. Delete your store.json
(see Privacy & safety for its location) and sign in again — that
re-registers the app with the current permissions.
The browser didn't open during login. The assistant will show you a link — open it manually to finish, then sign in again.
The sign-in page can't connect / port already in use. The login uses a
local web address on port 8765. If another program is using it, set a
different free port before launching the app by adding an environment variable
QCDB_CALLBACK_PORT (for example 8766), then sign in again.
It can't find python. Reinstall Python with "Add to PATH" ticked
(Windows), or use python3 in the config.
pip install -e . # editable install
python -m qcdatabase_mcp # run the stdio server directly
pip install -e '.[dev]' # editable install + test deps
pytest # run the test suiteLayout:
src/qcdatabase_mcp/
__main__.py # entry point + CLI (chooses stdio vs. hosted HTTP)
server.py # FastMCP server + all tools + local filesystem guard
hosted.py # multi-user hosting: OAuth resource server, token verify, sessions
client.py # HTTP client: bearer auth, auto-refresh, errors, pagination, path safety
auth.py # OAuth2 (PKCE + dynamic client registration) login & refresh (stdio)
config.py # local token / project storage (stdio)
tests/
test_security.py # guard, token verifier, path safety, pagination, refresh, ...
mcp_server_spec.md # the API + behaviour spec this server implements
CLAUDE.md # contributor invariants (filesystem safety, credential handling)Environment variables (stdio mode):
QCDB_CALLBACK_PORT — local OAuth callback port (default 8765).
QCDB_CONFIG_DIR — override where tokens/settings are stored.
mcp.qcdatabase.ai)By default the server speaks MCP over stdio — one local user, sign-in via the
login tool. Pass --http to run the multi-user hosted server instead, which
serves the Streamable HTTP transport at /mcp, plus a public home page
at / (connection instructions for humans) and a health check at /health
(for load balancers and uptime monitors).
Try it on your own machine (creates a .venv, installs, runs on
http://127.0.0.1:8000):
./scripts/run-local.sh # Mac/Linux
.\scripts\run-local.ps1 # Windows (PowerShell)
scripts\run-local.bat # Windows (double-clickable / cmd)Then open http://127.0.0.1:8000/ in a browser.
Deploy it on a server so that git pull + restart is a complete deploy —
the full walkthrough (systemd unit, nginx/Caddy configs, verification
checklist, troubleshooting) is in deploy/README.md:
cp deploy/example.env .env # set QCDB_MCP_RESOURCE_URL=https://mcp.example.com
./scripts/run-server.sh # binds 127.0.0.1:8000; put a TLS proxy in frontBehind nginx you MUST forward the original Host header (
proxy_set_header Host $host;) — the provideddeploy/nginx.confdoes. Without it, the DNS-rebinding protection rejects every authenticated request with421, which looks like "OAuth works but no tool call ever does". Caddy (deploy/Caddyfile) does the right thing by default.
In hosted mode the server is an OAuth 2.0 resource server (per the MCP authorization spec) — there are no shared secrets and nothing is stored on disk:
Each MCP client signs its own user in against QCDatabase.AI (discovered from
the /.well-known/oauth-protected-resource document this server publishes) and
sends that user's access token as Authorization: Bearer … on every request.
The server verifies the token against /api/whoami/, identifies the user,
and acts as them. Unauthenticated requests get 401 with a WWW-Authenticate
header pointing clients at the authorization server, so sign-in is automatic.
Per-user session state (the active project) is kept in memory keyed by a
globally-unique identity (tenant + user id, never the raw token), so many people
share one deployment without ever seeing each other's work. Verification fails
closed — a token that doesn't resolve to a user is rejected. (State resets on
restart — users just re-run set_project.)
DNS-rebinding protection validates the Host/Origin of every request
(forged Host → 421, forged Origin → 403).
The login / logout tools become no-ops in hosted mode (sign-in is the client's
job); everything else works identically to stdio.
Hosted-mode configuration (flags override env):
QCDB_MCP_HTTP=1 — same as --http.
--host / QCDB_MCP_HOST, --port / QCDB_MCP_PORT — bind (default
127.0.0.1:8000).
--resource-url / QCDB_MCP_RESOURCE_URL — this server's public URL and OAuth
resource id; required when binding a non-loopback host.
--issuer-url / QCDB_MCP_ISSUER_URL — the OAuth authorization server (default
https://qcdatabase.ai).
QCDB_MCP_ALLOWED_HOSTS / QCDB_MCP_ALLOWED_ORIGINS — extra allow-list entries
(comma-separated), e.g. when fronted by additional hostnames.
QCDB_MCP_TOKEN_CACHE_TTL — seconds a verified token is trusted before
re-checking /api/whoami/ (default 60). This is also the window in which a
token revoked upstream keeps working here; lower it to shrink that window.
QCDB_MCP_TOKEN_NEG_CACHE_TTL — seconds a failed verification is remembered
(default 5), which blunts garbage-token amplification against the API.
QCDB_MCP_STATELESS — serve each request without a server-held MCP session
(default 1). Leave on: stateful sessions break on restarts, redeploys, and
multi-replica setups ("session not found"). Set 0 only if you need
server-initiated messages within a session.
QCDB_MCP_JSON_RESPONSE — answer POSTs with plain JSON instead of an SSE
stream (default 1). Leave on: buffering proxies (nginx's default) stall SSE
and the client times out; none of this server's tools stream partial results.
TLS. Terminate TLS at a reverse proxy in front of the server (never expose
plain HTTP publicly) and forward the real Host header.
Resource indicator (kept open). This server accepts any valid QCDatabase-
issued token and takes its resource id from QCDB_MCP_RESOURCE_URL, so anyone can
fork it and host on their own domain without special AS configuration. For strict
RFC 8707 audience binding, an operator may configure their authorization server
to issue tokens bound to their MCP URL — but it is not required.
Scaling across replicas. The only shared state is each user's pinned project —
small, non-secret, and disposable (lost pins just mean re-running set_project).
Pick whichever fits your deployment:
Single instance (default). In-memory store, nothing to run. Best for most self-hosters.
Sticky sessions. Several replicas behind a load balancer that routes each user to the same replica; still in-memory, but a replica restart drops its users' pins.
Shared store (Redis). Set QCDB_MCP_REDIS_URL and install the extra
(pip install 'qcdatabase-mcp[redis]'). All replicas share state and it
survives restarts. Pins expire after QCDB_MCP_SESSION_TTL seconds idle
(default 8h). To plug in a different backend, implement the two-method store in
hosted.py (get_active_project / set_active_project) and return it from
build_session_store.
(The token-verification cache is intentionally per-replica — each rebuilds it from
/api/whoami/, so it needs no sharing.)
Licensed under the MIT License (see LICENSE).
Attach a photo to an object (for example object_type='map_item' with that item's id). Optionally add a caption.
| Name | Required | Description | Default |
|---|---|---|---|
| object_type | Yes | ||
| object_id | Yes | ||
| file_path | Yes | ||
| caption | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fails to disclose side effects (e.g., replaces existing photo?), error conditions, or authentication needs. Only states the basic action of attaching, missing critical 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?
Description is a single sentence with an example, no redundant information. Concisely communicates core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and an output schema (undescribed), the description lacks details on return values, constraints, and prerequisite conditions. Completeness is insufficient for an agent to reliably use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description only provides an example for 'object_type' and notes 'caption' is optional, but does not explain 'object_id', 'file_path' (format/location), or 'caption' constraints. Adds almost no meaning beyond parameter names.
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?
Description clearly states the action (attach photo) and target (object) with an example using 'map_item'. It distinguishes from sibling upload tools by specifying 'photo' versus documents/drawings, but could be more explicit about the distinction.
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?
Provides an example of when to use (attaching to map_item) but lacks guidance on prerequisites, alternative tools (e.g., upload_document for non-photo files), or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether you are signed in and which project is currently active.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description clearly indicates a read-only check. It discloses the specific aspects checked (sign-in, active project) but doesn't explicitly state it's non-mutating.
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 a single, concise sentence that efficiently conveys the tool's purpose without unnecessary 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?
For a simple check tool with no parameters and an output schema, the description sufficiently covers the tool's behavior and purpose without needing to elaborate on return values.
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?
No parameters exist, so schema coverage is complete. The description adds no parameter-level detail, which is acceptable for a zero-parameter tool. Baseline 4.
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 clearly states the tool checks sign-in status and active project, distinguishing it from related authentication tools like login, logout, and set_project.
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 usage for checking authentication state before actions, but does not explicitly state when to use versus alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a form submission complete. Completed forms are evidence that can satisfy reference requests. This locks the submission - only do it when the user confirms the form is finished.
| Name | Required | Description | Default |
|---|---|---|---|
| submission_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that the action locks the submission (irreversible state change) and that completed forms satisfy reference requests. Does not detail permissions, errors, or side effects beyond locking.
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 sentences: first states the action, second explains consequence and usage. Efficient and front-loaded with the key verb 'Mark'. No wasted words.
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?
Tool is simple (1 param) and has an output schema, so return values are covered. Description explains purpose, usage, and behavioral implications (locking). Could mention what happens if submission is already complete, but still adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% meaning description adds nothing about parameters. The single parameter 'submission_id' is self-explanatory from its name, but the description does not elaborate on its format or constraints. With only one simple parameter, the lack of description is acceptable but not ideal.
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?
Description clearly states the action ('Mark a form submission complete') and the resource. It distinguishes from sibling tools like 'mark_itp_complete' by specifying form submissions. Also adds context about evidence and reference requests.
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 says 'only do it when the user confirms the form is finished', providing clear when-to-use guidance. Does not mention alternatives or when not to use, but the context of locking implies it is a final action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new inspection-form submission from a form schema id. 'data' is an optional JSON object of initial field values. It is created as a draft; use 'complete_form_submission' to lock it once finished.
| Name | Required | Description | Default |
|---|---|---|---|
| form_schema | Yes | ||
| title | No | ||
| report_date | No | ||
| data | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the submission is created as a draft and mentions the optional 'data' field. However, it does not reveal other behavioral traits such as required permissions, side effects, or behavior on duplicate calls.
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 extremely concise with two sentences. Every sentence adds value: first states the purpose and key parameter, second clarifies the draft behavior and workflow. No wasted words.
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?
An output schema exists, so return values are covered. However, with 4 parameters, only 2 are explained, and there are no annotations to cover behavioral expectations. The description is incomplete for a tool with moderate complexity.
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 description explains only two of four parameters: 'form_schema' (the schema id) and 'data' (optional initial values). It does not explain 'title' or 'report_date', which are present in the schema with default values but no further description. Given 0% schema description coverage, the description should compensate more.
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 uses specific verbs ('start a new ... submission') and clearly identifies the resource ('inspection-form submission') and key input ('form schema id'). It distinguishes the tool from siblings like 'complete_form_submission' which locks the submission.
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 explicitly states the tool is for starting a new submission as a draft and directs the user to use 'complete_form_submission' to lock it. This provides clear context on the workflow, though it does not explicitly state when not to use it or describe alternatives for other use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a map item (a weld, flange, fitting...) pinned to a drawing. Use a schema id from 'list_map_item_schemas'. 'data' is a JSON object of the schema's custom fields; for fields that map to a controlled list, put that list item's 'pseudo_code' pill (from 'list_list_items') as the value instead of free text.
| Name | Required | Description | Default |
|---|---|---|---|
| drawing_id | Yes | ||
| schema_id | Yes | ||
| label | Yes | ||
| notes | No | ||
| data | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions 'pinned to a drawing' and how to structure 'data', but does not explain side effects, required permissions, error conditions, or whether the operation is reversible. The output schema exists but the description does not reference return 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?
The description is extremely concise: two sentences, no wasted words. The first sentence states purpose with examples; the second provides actionable guidance. Every sentence 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?
Given the output schema exists, return values need no explanation. The description covers core creation behavior and provides crucial cross-references to sibling tools. However, it lacks details on required parameters like drawing_id (no format or validation), and does not mention potential failures or constraints. Adequate but incomplete for a 5-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning for schema_id (use from list_map_item_schemas) and data (JSON with pseudo_code for controlled lists). However, it does not explain drawing_id, label, or notes beyond their names. The description adds value but leaves gaps for 3 of 5 parameters.
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?
Description clearly states the tool creates a map item (weld, flange, fitting) pinned to a drawing, using specific examples. It distinguishes from siblings like list_map_items or mark_map_item_accepted by focusing on creation. The verb 'create' is explicit and the resource 'map item' is specific.
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?
Description provides clear prerequisites: schema id comes from list_map_item_schemas, and for controlled list fields use pseudo_code from list_list_items. It implicitly guides when to use this tool (when creating a map item) vs listing or marking. However, it does not explicitly state when not to use or alternatives for other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a note (observation, action item, issue) on the current project. Optionally make it private, set a severity, anchor it to a page_url, and assign (@mention) it to a project member by their user id.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| is_private | No | ||
| severity | No | ||
| page_url | No | ||
| assigned_to | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the creation behavior and parameters but lacks details on side effects (e.g., notifications), reversibility, or output. With no annotations, the description carries full burden but is not fully transparent.
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 concise sentences: first for purpose, second for optional parameters. No fluff, front-loaded, easy to parse.
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?
Covers all parameters with use context but misses explaining the output (an output schema exists but not described) and the need for a set active project. Adequate for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds clear meaning for each parameter: private, severity, page_url, assigned_to (as @mention by user ID). This compensates for missing schema descriptions.
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 clearly states the tool's function: creating a note on the current project, listing note types (observation, action item, issue), and optional fields. It distinguishes from sibling tools like list_notes and resolve_note.
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 usage for adding notes but does not explicitly state when to use this tool over alternatives like list_notes or resolve_note, nor does it mention prerequisites like setting the active project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Link a source item to its proof - this is how a turnover package gets completed. source_type is map_item, list_item, or itp_line_item. target_type is 'document' or 'form' (a form submission). Creating a matching reference fulfils any open reference request for that item.
| Name | Required | Description | Default |
|---|---|---|---|
| source_type | Yes | ||
| source_id | Yes | ||
| target_type | Yes | ||
| target_id | Yes | ||
| status | No | ||
| note | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that creating a matching reference fulfills any open reference request for that item, which is a behavioral consequence beyond the action. No annotations present, so description carries full burden. Could mention side effects or permissions but still informative.
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 sentences, each serving a purpose: main action, parameter constraints, and side effect. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description need not detail return values. It covers the tool's role, param values, and consequence (fulfilling requests). Fully adequate for a medium-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds crucial meaning by specifying allowed values for source_type and target_type. Other parameters (source_id, target_id, status, note) lack detail, but the provided info is highly useful for correct invocation.
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?
Clearly states the tool links a source item to its proof, explains it completes a turnover package, and lists allowed values for source_type and target_type. Distinguishes from sibling create_reference_request by noting it fulfills open requests.
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?
Provides context that this is how a turnover package gets completed and that it fulfills open reference requests, giving implicit guidance on when to use it. No explicit exclusions but sibling tool exists for requests.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a reference request (record that a source item still needs proof). item_type is map_item, itp_item, or list_item. reference_type is 'document' (then give document_folder) or 'custom_form' (then give form_schema). Optionally assign it to a project member and add a description.
| Name | Required | Description | Default |
|---|---|---|---|
| item_type | Yes | ||
| item_id | Yes | ||
| reference_type | Yes | ||
| document_folder | No | ||
| form_schema | No | ||
| assigned_to | No | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the creation action and parameter constraints but lacks details on side effects, permissions, error behavior, or idempotency.
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 concise sentences with front-loaded purpose, accurate parameter details, and no redundant 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?
Adequate for creation tool with 7 parameters and an output schema, but lacks explicit contrast with sibling create_reference and does not describe output or error scenarios.
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 compensates by explicitly listing allowed values for item_type and reference_type and explaining conditional parameters (document_folder, form_schema). Missing details on item_id and defaults.
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 clearly states the tool creates a reference request (a record that a source item needs proof), specifies the allowed values for item_type and reference_type, and distinguishes from sibling create_reference by focusing on pending proof needs.
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 when to use (when a source item still needs proof) but does not explicitly state when not to use or contrast with alternatives like create_reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download the blank fillable PDF for a folder to a local path so you can fill it in (ideally flatten it) before submitting.
| Name | Required | Description | Default |
|---|---|---|---|
| folder_id | Yes | ||
| save_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully bears transparency. Clearly indicates a non-destructive download operation. Does not mention side effects, authentication, or rate limits, but for a simple download it is adequate.
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?
Single sentence front-loads the action, no filler. Every word adds value – 'blank fillable PDF', 'local path', 'fill in', 'flatten'. Ideal conciseness for a tool 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?
Given the tool's simplicity (2 required params, no nested objects), the description covers the core purpose and usage tip. Lacks output details (but output schema may provide that), and could clarify distinction from 'get_fillable_template' more explicitly, but still sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must clarify parameters. It explains 'folder_id' as identifying the folder and 'save_path' as the local destination, but lacks details like format (e.g., folder_id as string ID) or path requirements (e.g., must include filename). Adds some value but not comprehensive.
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?
Description clearly states the tool downloads a blank fillable PDF to a local path, with specific verb and resource. It distinguishes from siblings like 'get_fillable_template' (likely metadata retrieval) and 'submit_fillable_template' (submission). The 'ideally flatten it' tip further clarifies the purpose.
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?
Implicitly suggests using this to get the blank template before filling and submitting, but lacks explicit when/not-to-use or alternatives. No direct comparison with 'get_fillable_template' or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show which project is currently active for this session.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It fails to mention what happens if no project is active, whether authentication is required, or if the session state persists.
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?
Single sentence, front-loaded, no wasted words. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity and presence of output schema, the description adequately conveys the core function but could add context about session behavior or return format.
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?
No parameters exist, so the description does not need to compensate. Baseline score of 4 applies per the rubric.
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?
Description clearly states the tool shows the currently active project for the session, using a specific verb and resource. It effectively distinguishes from sibling tool 'set_project'.
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 usage to check the active project but offers no guidance on when to use this tool versus alternatives, nor does it mention prerequisites like authentication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one document's details, including its AI-extracted structured data.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It only states that the tool retrieves details and AI-extracted data, but does not disclose any behavioral traits such as authentication requirements, rate limits, or side effects. The output schema exists but the description adds minimal 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?
The description is a single, front-loaded sentence that efficiently conveys the core action and result without any extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists), the description covers the basic purpose but lacks guidance on prerequisites (e.g., obtaining a document ID) and does not fully leverage the context to provide a complete picture.
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 0% schema description coverage and no parameter details in the description, the parameter 'document_id' relies solely on its name. The description adds no additional meaning about format, constraints, or source, which is insufficient for a missing schema coverage 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?
The description clearly states the verb 'get' and the resource 'one document's details', and differentiates from siblings like list_documents (which lists) and set_document_extracted_data (which sets). The mention of 'AI-extracted structured data' adds specificity.
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 explicit when-to-use or when-not-to-use guidance is provided. The context implies use for retrieving a single document versus listing or uploading, but no alternatives or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a fillable template's form fields and its project-resolved autofill values, so you know what to fill in before downloading and submitting it.
| Name | Required | Description | Default |
|---|---|---|---|
| folder_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It correctly identifies the tool as read-only ('Read'), which is consistent with its purpose. It adds context about returning autofill values, but lacks details on permissions, rate limits, 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?
Single sentence, directly states the tool's purpose and outcome, no redundant 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 description covers the tool's core purpose but does not address error handling, prerequisites, or the significance of 'project-resolved autofill values'. Output schema is present, so return structure is covered externally, but parameter documentation 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 0%, yet the description does not explain the 'folder_id' parameter, its format, or how to obtain it. This leaves the agent without guidance on what to provide, failing to compensate for the missing schema descriptions.
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?
Description clearly states the action (Read) and resource (fillable template's form fields and autofill values), with the purpose (to know what to fill before download/submit). This distinguishes it from siblings like list_fillable_templates (list all) and download_fillable_template (download).
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 indicates use before downloading and submitting, providing clear context. However, it doesn't explicitly state when not to use this tool or mention alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the document folders (document types) and their extraction schemas - e.g. an 'MTR' folder that extracts heat number and material grade. Use a folder id when uploading a document so it is filed and extracted correctly.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations. The description adds context about extraction schemas, but does not explicitly state that the operation is read-only or safe. Simple list tool, so not critical, but missing explicit safety disclosure.
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 sentences, no fluff, front-loaded with the core action and an example to clarify. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and a straightforward purpose, the description fully covers what the tool does, its output (folders and schemas), and how to use the results. Output schema exists, so no need to detail return values.
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?
No parameters (0). The description enriches understanding by explaining what the output contains (folders with extraction schemas) and why it's useful, beyond the empty 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 clearly states the purpose: listing document folders (document types) and their extraction schemas, with a concrete example (MTR). It distinguishes from siblings like list_documents by focusing on folder types versus documents.
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 explains that folders are used when uploading documents, implying this tool is a prerequisite. No explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List uploaded documents in the current project. Optionally filter by a document folder id, status (uploading/processing/extracting/ready/error), or a search term.
| Name | Required | Description | Default |
|---|---|---|---|
| folder_id | No | ||
| status | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It does not mention pagination, sorting, permission requirements, or what happens when no documents are found. The lack of such details reduces transparency.
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 sentences with no wasted words. The main action is front-loaded, and optional filters are listed succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 optional parameters, no annotations, and an existing output schema, the description covers the essential purpose and filters. It lacks pagination details but is adequate for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains that 'folder_id' is a document folder id, 'status' can be 'uploading/processing/extracting/ready/error', and 'search' is a search term. However, it does not specify format or behavior beyond the status enum.
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?
Description clearly states the action ('list'), resource ('documents'), and scope ('current project'), with optional filters. It distinguishes itself from siblings like 'get_document' (single document) and 'attach_photo' (image-specific).
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 description: use for listing documents with optional filters. No explicit when-to-use or when-not-to-use guidance is given, nor mention of alternatives like 'get_document' for a specific document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List document folders that publish a fillable PDF template (RIR, inspection checklist, test report...) you can fill out and file.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey safety and behavior. It states the tool returns folders that publish fillable templates (filtered), but omits details on authentication, pagination, or rate limits. Basic read operation inferred but not fully transparent.
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?
Single sentence of 20 words efficiently states the tool's purpose with examples. Front-loaded with key action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no nested objects) and the presence of an output schema, the description adequately covers what the tool does. It could mention the output structure but the schema handles that.
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 has zero parameters, so schema coverage is 100% trivially. The description adds value by specifying the type of folders listed (fillable template folders), which compensates for the lack of parameter details.
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 clearly states the tool lists document folders that contain fillable PDF templates, specifying examples like RIR and inspection checklists. It distinguishes from sibling tools like list_document_folders (all folders) and list_documents (files).
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 use when seeking folders with fillable templates, but does not explicitly state when not to use it or compare to alternatives like list_document_folders. No exclusions or context for other cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List inspection-form submissions in the current project. Optionally filter by a form schema id or status (draft/completed).
| Name | Required | Description | Default |
|---|---|---|---|
| form_schema | No | ||
| status | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not explicitly state that this is a read-only operation, nor does it mention authorization needs, rate limits, or behavior when no project is set. The description lacks behavioral context beyond the basic list action.
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 a single, well-structured sentence that is efficient and front-loaded. Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the simplicity of the tool (listing with optional filters), the description is largely complete. However, it omits details like ordering, pagination, or result limits, which could be important for an agent.
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 input schema has 0% description coverage, but the description adds meaning by explaining that 'form_schema' is a form schema id and 'status' can be 'draft/completed'. This provides essential context beyond the schema properties.
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 clearly states the tool lists inspection-form submissions in the current project, with optional filtering. The verb 'list' and resource 'form submissions' are specific and distinguish it from sibling tools like create_form_submission or complete_form_submission.
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 usage for listing form submissions, and the context of 'in the current project' sets scope. However, it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ITP (Inspection & Test Plan) line items in the current project - the required inspection/test steps. Optionally filter by package id, and by completed / accepted (true or false).
| Name | Required | Description | Default |
|---|---|---|---|
| package | No | ||
| completed | No | ||
| accepted | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must handle behavioral disclosure. It indicates a read-only listing operation, but does not mention pagination, ordering, or that it does not modify data. Adequate for a simple list tool, but could be more thorough.
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 sentence, front-loaded with purpose. Very concise with no wasted words. Could be more structured but efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (3 optional params, output schema exists), the description covers the essential purpose and filters. It is complete enough for an agent to use correctly, though it could mention scope more explicitly.
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 has 3 parameters with 0% coverage. Description adds meaning by explaining package as 'package id' and completed/accepted as boolean filters. However, it does not explain default values or null meaning. Adds value beyond schema but not extensively.
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?
Clearly describes the tool as listing ITP line items in the current project, with optional filters. The verb 'list' and resource 'ITP line items' are specific, and the description distinguishes it from sibling tools like mark_itp_complete or list_lists.
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 when to use (to list inspection/test steps, with optional filtering) but does not explicitly mention when not to use or provide alternatives. The context of 'current project' is implied but not defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the entries in one controlled-vocabulary list. Each entry includes a 'pseudo_code' pill token - paste that verbatim into a map item field so the value stays linked to the canonical list entry instead of being free text.
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It correctly indicates a read-only operation ('Read') and explains the pseudo_code token, but does not disclose rate limits, authentication needs, or error 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?
The description is two sentences, front-loaded with the core purpose, and adds a useful detail about pseudo_code tokens. Every word earns its place with no fluff.
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 explains the pseudo_code token but omits other potential return fields. The output schema exists but is not shown; however, the description could provide more context on what else is returned. Parameter documentation is weak.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter list_id has 0% schema description coverage, and the description does not explain what the list_id represents or how to obtain it. Given the low coverage, the description should compensate but fails to do so.
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 starts with 'Read the entries in one controlled-vocabulary list,' clearly specifying the verb and resource. It distinguishes from sibling tools like list_lists and list_map_items by focusing on entries within a single list.
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 a use case (linking list entries to map items via pseudo_code tokens) but does not explicitly state when to use or when not to use this tool, nor does it mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the project's controlled-vocabulary lists (welders, weld types, materials, pipe sizes, equipment, etc.). Use 'list_list_items' to read one.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The tool name and description imply a read-only listing operation. No annotations are provided, so the description carries the full burden. While it doesn't explicitly state behavior (e.g., no side effects), the simple nature and examples make it clear enough. A score of 4 is appropriate as it adds value beyond the name.
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 sentences, no wasted words. The information is front-loaded, concise, and every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema, the description is complete. It covers what the tool does, provides examples, and directs to related tools. No additional context needed.
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 input schema has no parameters, so baseline is 4. The description adds value by giving examples of the lists' content, which helps the agent understand what to expect.
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 clearly states the tool lists controlled-vocabulary lists for the project, with specific examples like welders and materials. It also distinguishes itself from the sibling 'list_list_items' by directing the agent to use that tool to read one list.
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 guides when to use this tool (to list all controlled-vocabulary lists) and when to use the alternative 'list_list_items' (to read one specific list). Provides clear context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List map items (welds, flanges, fittings...) in the current project. Optionally filter by drawing id, schema id, status, or a search term.
| Name | Required | Description | Default |
|---|---|---|---|
| drawing_id | No | ||
| schema_id | No | ||
| status | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately portrays the tool as a read operation that lists items with optional filtering. No annotations exist, so the description carries the full burden and provides adequate transparency for a list tool.
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 a single concise sentence that front-loads the purpose and includes examples and filter options; no extraneous 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?
While the description covers the tool's action and filters, it omits the important context that the 'current project' must be set via set_project first, which is a prerequisite not mentioned.
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 0% schema description coverage, the description explicitly names and explains the four filter parameters (drawing id, schema id, status, search term), adding meaning beyond the schema field names.
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 the verb 'List' and resource 'map items' with examples (welds, flanges, fittings), and distinguishes from siblings like create_map_item and list_map_item_schemas.
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 clearly states the tool lists items with optional filters, but does not explicitly discuss when to use this tool versus alternatives or mention prerequisites like setting the current project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the map item schemas available in this project. A schema (e.g. 'Weld') defines the custom fields a map item carries - you need its id to create one.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses that the tool lists schemas (read operation) and explains what a schema is. It does not mention side effects, but it is a simple list with no parameters, and an output schema exists to document return structure. Additional details about permissions or pagination are not needed.
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 concise at two sentences, front-loaded with the primary action, and each sentence adds value: the first states the action, the second provides critical context and usage guidance. No redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description is nearly complete. It explains the tool's purpose, provides an example, and links to a use case (creating a map item). It could mention the need for an active project context, but the phrase 'in this project' hints at it, and sibling tools include project selection.
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?
No parameters exist (empty input schema), so no parameter documentation is required. The baseline score of 4 applies because the description adds value by explaining the context and meaning of the schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists map item schemas with a specific verb ('list') and resource ('map item schemas'), provides an example ('Weld'), and explains the purpose (needed to create a map item). It distinguishes from siblings as no other sibling lists schemas.
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 when to use this tool: before creating a map item to get the schema id. It does not explicitly state when not to use it or mention alternatives, but no direct sibling exists for this function. The context hint 'available in this project' is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the public notes feed for the current project. status can be 'all' (default), 'open', or 'resolved'.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | all |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose all behavioral traits. It states the tool is read-only (list) and applies to the current project, but lacks details on pagination, ordering, rate limits, or authentication requirements. The output schema exists but doesn't cover behavioral aspects.
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 sentences with no wasted words. The purpose is front-loaded, and the parameter explanation is concise. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter) and the existence of an output schema, the description covers the essential aspects: what it lists, for which project, and the filter options. It is slightly lacking on prerequisites like login/project selection, but still fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by listing the three possible status values ('all', 'open', 'resolved') and the default. This adds meaning beyond the schema's type definition. However, it does not explain the semantics of each status (e.g., what 'resolved' means).
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 clearly states the action (List) and the resource (public notes feed), differentiating it from sibling tools like create_note and resolve_note. It also mentions the status filter options, which aligns with the input 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 usage for listing notes in the current project's public feed, but does not explicitly state when to use this tool over others (e.g., list documents) or mention exclusions. The context of 'current project' is noted but not explained as a prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the active members of the current project (use their ids when assigning notes or reference requests).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'list' without disclosing if this is a read-only, safe, or any potential side effects. It does not mention authentication needs or that the project must be active.
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 a single sentence that efficiently communicates the action and a usage hint. It is front-loaded with the core function. Minor improvement would be separating the hint for 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?
Given no parameters and an output schema, the description is adequate but misses a key context: the 'current project' must be set via a separate tool. This prerequisite is not mentioned, which could lead to confusion.
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?
There are zero parameters and schema coverage is 100%, so baseline is 4. The description adds value by explaining the purpose of the returned IDs, exceeding the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'active members of the current project', making the purpose specific and unambiguous. No sibling tool has a similar purpose, so differentiation is inherent.
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 provides a downstream usage hint (use ids for assigning notes or references) but does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites like setting the current project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the projects in your connected organization. Optionally filter by a search term (name, code, client, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| search | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond the basic read operation. Missing details on authentication requirements, rate limits, data freshness, or side effects, even for a simple list tool.
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 sentences, no wasted words. First sentence states purpose and scope; second adds the optional filter. Front-loaded and efficient.
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 covers the core functionality and parameter, but lacks information on pagination, result ordering, or output schema details (though output schema exists). For a simple list tool, this is mostly sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'search' parameter by listing examples of filterable fields (name, code, client, etc.), compensating for the 0% schema description coverage. This is helpful but could be more precise about search syntax.
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 clearly states the verb ('list') and resource ('projects'), and specifies the scope ('in your connected organization'). It distinguishes from siblings like 'get_active_project' (single project) and 'list_project_members' (different resource) by focusing on all projects with optional 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?
No guidance on when to use this tool versus alternatives (e.g., 'get_active_project' or 'set_project'). Lacks explicit conditions, prerequisites, or exclusions, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List reference requests - the tracked 'still-needs-proof' items. By default shows OPEN ones, which together are the punch list standing between the team and a complete turnover package. Pass status='all' (or fulfilled/cancelled) or an assignee user id to filter.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | open | |
| assigned_to | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states the listing behavior and filtering, but does not disclose read-only nature, authentication needs, rate limits, or other behavioral traits beyond what is obvious.
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 sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only two simple parameters and an output schema exists, the description covers inputs and default behavior adequately. Missing details like pagination or ordering, but these are not critical for this simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds significant meaning: it explains the default 'open' status, valid values ('all', 'fulfilled', 'cancelled'), and that 'assigned_to' filters by user ID. This compensates well for the lack of schema descriptions.
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 clearly states the verb 'List' and the resource 'reference requests', and explains they are 'tracked still-needs-proof items'. It does not explicitly differentiate from sibling tools like 'list_references', but the purpose is 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?
The description provides guidance on default behavior (shows OPEN) and how to filter by status or assignee, implying when to use. It could be improved by explicitly stating when not to use or mentioning alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the references already attached to a source item. source_type is map_item, list_item, or itp_line_item.
| Name | Required | Description | Default |
|---|---|---|---|
| source_type | Yes | ||
| source_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states it lists references, with no disclosure of read-only nature, side effects, or other behavioral traits.
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 sentences with no wasted words, front-loaded with the main purpose. Highly concise and structured.
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 is minimal but adequate for a simple list tool, especially given the presence of an output schema. However, it could explain what a reference is or what the output contains.
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 adds meaning by specifying allowed values for source_type. However, source_id is not elaborated, and the reference concept is not explained, leaving some ambiguity.
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 clearly states the verb ('list') and resource ('references'), and specifies the source types (map_item, list_item, or itp_line_item), distinguishing it from siblings like create_reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other list tools or alternatives. The description does not provide context for usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the organizations (tenants) your account belongs to. Your login is pinned to one of them, chosen at sign-in.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It adds context about login pinning to a tenant but does not disclose other behavioral traits like side effects, rate limits, or required permissions. The simple read-only nature is implied but not explicit.
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 concise sentences, no wasted words. The purpose is front-loaded, and the additional context about login pinning is succinct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and an existing output schema, the description adequately covers the tool's behavior. It explains what a tenant is and the pinned-login context, leaving return details to 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?
No parameters exist, so schema coverage is 100%. The description adds no parameter details, but none are needed. Baseline for 0 parameters is 4.
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 clearly states the tool 'lists the organizations (tenants) your account belongs to,' with a specific verb and resource. It distinguishes from sibling list tools (e.g., list_documents, list_projects) by focusing on tenants.
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 explicit 'when to use' or alternatives are provided. The description implies usage for retrieving tenant information but offers no guidance on when not to use or how it relates to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sign in to QC Database. Opens your web browser so you can log in and pick which organization (company workspace) to connect. Do this once; the connection is then remembered. You choose the project separately with 'set_project'.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose all behavioral traits. It mentions opening a web browser and remembering the connection, but does not address re-login behavior or error states, which are relevant for a login tool.
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 sentences, front-loads the main purpose, and contains no redundant 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?
Despite no annotations and no parameters, the description covers the essential aspects: action, browser launch, persistence, and project separation. It could mention potential outcomes like cancellation or error handling, but overall is fairly 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?
The input schema has no parameters, so the description does not need to add parameter information. Baseline score of 4 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 clearly states the verb 'Sign in' and the resource 'QC Database', and distinguishes itself from sibling tools like logout and set_project by explaining the workflow.
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 provides clear when-to-use guidance ('Do this once; the connection is then remembered') and references set_project for project selection, but does not explicitly state when not to use it (e.g., if already logged in).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sign out and forget the saved login on this computer.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool will 'forget the saved login on this computer,' indicating a destructive action on local state. It is fairly transparent but could explicitly mention session invalidation or side effects.
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 a single, concise sentence with no unnecessary words. It is efficiently front-loaded and to the point.
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?
While the tool is simple, the description lacks information about the return value or output (though output schema exists but is not shown). It also does not mention that the user must be logged in first. This leaves gaps for completeness.
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 has no parameters, and the schema coverage is 100%. There is nothing for the description to add beyond what the schema already provides, so it meets the baseline perfectly.
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 clearly states the tool's action: 'Sign out and forget the saved login on this computer.' It is specific and distinguishes itself from sibling tools like 'login' and 'auth_status'.
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 does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites like being logged in. However, the action is simple and the purpose implies usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an ITP line item accepted (must already be complete). This is a buy-off recorded under YOUR name. Only do this with the user's explicit go-ahead.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that acceptance is a buy-off recorded under the agent's name and requires explicit permission. Could mention idempotency or reversibility, but overall clear.
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 sentences, efficient and front-loaded with verb and key conditions. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, return values need no explanation. However, the parameter is not fully described, and the tool's effects (e.g., status change) are implied but not explicit. Adequate but has gaps.
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 description must explain the parameter. It only implies that 'item_id' identifies the ITP line item, but no details on format, source, or relationship to other tools. Insufficient for a 1-param tool.
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?
Description clearly specifies the verb 'Mark', resource 'ITP line item accepted', and adds context: must already be complete, recorded under agent's name, requires explicit go-ahead. This distinguishes it from siblings like 'mark_itp_complete' and 'mark_map_item_accepted'.
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 states precondition ('must already be complete') and permission requirement ('only do this with the user's explicit go-ahead'). Does not list when not to use or alternatives, but context is sufficient for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an ITP line item complete. This is a buy-off recorded under YOUR name. Only do this when the user confirms the activity is done - the user is responsible for the sign-off.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the buy-off is recorded under the agent's name, giving important attribution context. However, it does not describe whether the action is reversible or any side effects, limiting transparency for a mutation tool.
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 sentences efficiently convey purpose and usage guidelines without any redundant or extraneous 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?
Given the tool's simplicity (one param, output schema exists), the description adequately covers what it does, when to use it, and attribution. Lacks details on post-action state changes, but output schema may cover return value.
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 sole parameter 'item_id' has no schema description (0% coverage) and the tool description provides no additional meaning about what this ID represents or its format.
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 clearly states the verb 'mark' and resource 'ITP line item complete', distinguishing it from sibling tools like mark_itp_accepted (different status) and mark_map_item_complete (different object).
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 states when to use: only when user confirms activity is done. Implicitly warns against premature use by emphasizing user responsibility. Lacks explicit alternatives but context with siblings provides differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a map item accepted (must already be complete). This is a buy-off recorded under YOUR name. Only do this with the user's explicit go-ahead - the user is accountable for the acceptance.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that acceptance is a buy-off recorded under the agent's name and requires user consent. Does not mention error handling or reversibility, but provides key behavioral context beyond simple action.
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 sentences covering purpose, precondition, and usage guidance. No wasted words, front-loaded with key 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?
For a simple tool with one param and output schema, description adequately explains usage and precondition. Does not address return values or lifecycle details, but context from siblings suggests completion before acceptance.
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?
Single parameter 'item_id' is self-explanatory but description adds no extra meaning. Schema description coverage is 0%, so description fails to clarify what the ID refers to or any constraints.
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?
Description uses specific verb 'mark' and resource 'map item' with explicit precondition 'must already be complete'. Clearly distinguishes from sibling 'mark_map_item_complete' which marks complete rather than accepted.
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?
Description states when to use (item must be complete) and when not to (only with user's explicit go-ahead). Also notes accountability: 'recorded under YOUR name' and 'user is accountable for the acceptance.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a map item complete. This is a buy-off recorded under YOUR name and the current time. Only do this when the user has confirmed the work is done - the user is responsible for this sign-off.
| Name | Required | Description | Default |
|---|---|---|---|
| item_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral details: records under user's name, timestamp, and that it is a sign-off requiring user confirmation. With no annotations, this description compensates well by outlining 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 concise sentences: action, explanation of recording, and usage guidance. No unnecessary words, front-loaded with the action.
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?
Adequate for a simple one-parameter tool with an output schema. Covers purpose, usage conditions, and behavioral implications. Missing error conditions or edge cases, but not critical for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'item_id' has no description in schema or description text. While the tool name implies it refers to a map item, no additional semantics or constraints are provided beyond the schema's type declaration.
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?
Clearly states it marks a map item complete and describes it as a buy-off recorded under user name and current time. The tool name itself is descriptive, and the description reinforces the purpose. It distinguishes from siblings like 'mark_map_item_accepted' by specifying 'complete'.
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?
Provides explicit when-to-use: only when user has confirmed work is done. Emphasizes user responsibility for sign-off. However, it does not explicitly contrast with alternative statuses like 'accepted' or 'rejected'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a note resolved, with an optional resolution comment.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | ||
| resolution | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only mentions the action without disclosing side effects, reversibility, or any behavioral traits beyond the core operation. The description carries full burden but fails to add depth.
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 that efficiently conveys the tool's purpose without any unnecessary words or structure.
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 mutation tool with two parameters, the description covers the essential action. It could mention the output or any state changes, but overall it is adequate for the complexity level.
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 must compensate. It adds meaning to the 'resolution' parameter by stating it's optional and a comment. However, it does not elaborate on 'note_id' beyond the schema. The contribution is partial.
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 clearly states the action ('mark a note resolved') and the resource ('note'). It distinguishes from sibling tools like 'create_note' or 'list_notes' by specifying the resolution action.
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 usage when a note needs to be resolved, but provides no explicit guidance on when to use versus alternatives (e.g., other note operations) or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write structured fields back onto a document (used after you run your own 'bring your own AI' extraction). 'extracted_data' is a JSON object string matching the folder's schema.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | ||
| extracted_data | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It confirms writing fields back and explains that extracted_data must match the folder schema, but lacks details such as whether it overwrites existing data, required permissions, error handling, or update 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 sentences, no fluff. First sentence states purpose and usage, second clarifies a parameter. Every word 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?
Given the presence of an output schema (indicated by context signals), the description need not cover return values. However, for a mutation tool, it should disclose behavioral context like whether this is a partial update or full replacement, and any prerequisites. It provides adequate but not complete context.
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 description adds meaning to extracted_data by specifying it is a JSON object string matching the folder's schema, which is not evident from the schema (just 'string'). This compensates for the 0% schema description coverage. However, document_id is not explained further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Write structured fields back onto a document' and specifies the use case 'after you run your own bring your own AI extraction', clearly distinguishing it from other document operations like get_document or upload_document.
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 explicitly states when to use this tool (after extraction), providing clear context. However, it does not mention when not to use it or reference alternatives among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Choose the project to work in for the rest of this session. Almost every other tool uses it, so set it before doing anything else. Give either the exact project_id, or a name_or_code to search for (it must match exactly one project).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | ||
| name_or_code | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses session-wide effect and search behavior, but omits what happens on conflict or empty inputs. No annotations so burden is on description.
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 efficient sentences, front-loaded with purpose, no waste.
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?
Adequate for a simple tool with output schema; covers when to use, how to use, and key constraint.
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?
Adds meaning to parameters: project_id is exact, name_or_code is for search with uniqueness constraint. Schema coverage 0% so description compensates partially.
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?
Explicitly states it sets the session project, which is distinct from listing or getting active project. Clear verb and 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?
Tells agent to use this first because other tools depend on it. Explains parameter choice and constraint that name_or_code matches exactly one project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a filled PDF back into a template's folder as a document. Re-using a file_name creates a new version of that document. Set do_not_extract=True if you will supply the extracted JSON yourself. Note: filling the PDF stores the signed record; to also populate structured fields, follow up with 'set_document_extracted_data' on the returned document.
| Name | Required | Description | Default |
|---|---|---|---|
| folder_id | Yes | ||
| file_path | Yes | ||
| file_name | No | ||
| do_not_extract | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It explains that re-using file_name creates a new version and that setting do_not_extract=True skips extraction. It also notes that filling stores the signed record but structured fields require another tool. This gives good behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a note, front-loading the main action. Every sentence contributes meaning without redundancy. It is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It covers the main action, parameter effects, and a follow-up step. However, it lacks details on error conditions or prerequisites, but is largely complete for the tool's complexity.
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 compensate. It adds meaning for file_name (versioning) and do_not_extract (skip extraction), but does not describe the required parameters folder_id and file_path. Thus it partially compensates but not fully.
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 clearly states the tool submits a filled PDF back into a template's folder. It specifies the action (submit), resource (filled PDF), and destination (template's folder as a document). It distinguishes from siblings like upload_document by focusing on template submission.
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 provides guidance on when to use the do_not_extract parameter and mentions the follow-up tool set_document_extracted_data. It clearly implies the tool is for submitting filled PDFs, but does not explicitly state when not to use it or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize how close the current project is to a complete turnover package: open vs. fulfilled reference requests (the 'what's missing' list), and ITP line items not yet completed or accepted.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It describes the output (summary of reference requests and ITP items) but does not disclose read-only nature, required permissions, or other behavioral traits beyond the summary function.
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 a single concise sentence that conveys the tool's purpose and key outputs without unnecessary detail. Slightly more structure could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (read-only summary with no parameters) and presence of output schema, the description adequately covers what the tool does and what it returns. It is sufficient for the context.
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?
No parameters exist, so description does not need to add parameter information. Schema coverage is 100% by default, and baseline for 0 params is 4.
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 clearly states the tool summarizes the turnover package completeness by referencing open vs fulfilled reference requests and ITP line items not yet completed/accepted. It distinguishes itself from sibling tools that list individual items.
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 tool is used to get a summary of turnover package progress, but does not explicitly state when to use it versus alternatives or when not to use it. No exclusions or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a record (MTR, NDE report, certificate, procedure, etc.) to the current project. Optionally file it under a document folder id (recommended, so the right extraction schema runs). Set do_not_extract=True if you will supply the extracted data yourself with 'set_document_extracted_data'.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| folder_id | No | ||
| do_not_extract | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses extraction behavior and the option to supply data later via set_document_extracted_data, but lacks details on success output, error handling, or permissions. No annotations provided to supplement.
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 concise sentences that front-load the core purpose then provide optional parameter guidance. No redundant 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?
For a 3-param tool with an output schema not shown, the description covers key behaviors. Lacks prerequisites like login/project selection but is adequate for typical use.
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 0% schema coverage, description explains the purpose of file_path (implied), folder_id (recommended for extraction), and do_not_extract (when to set). Adds meaningful context beyond the bare 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?
Description clearly states the tool uploads a record (MTR, NDE report, etc.) to the current project, distinguishing it from sibling tools like upload_drawing which target specific file types.
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?
Provides clear guidance on using folder_id for proper extraction schema and when to set do_not_extract=True. Does not explicitly contrast with siblings but context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload an isometric drawing (PDF) to the current project. Multi-page PDFs are split into one drawing per sheet. Set do_not_extract=True to skip the server-side AI extraction.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| do_not_extract | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of behavioral disclosure. It reveals key behaviors: multi-page PDFs are split per sheet, and AI extraction can be skipped via do_not_extract=True. No mention of destructive behavior or auth needs, but the behavior is well-covered for a file upload tool.
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 sentences, zero waste. Front-loaded with the core action, followed by critical behavioral details. Every sentence 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?
Given the tool has 2 parameters, an output schema, and no nested objects, the description covers the key behaviors: multi-page splitting and extraction skip. It's complete enough for an AI 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?
Schema coverage is 0%, so the description must explain parameters. It clarifies file_path (implied as the source) and the do_not_extract parameter (controls server-side extraction). This adds meaning beyond the bare 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 clearly states 'Upload an isometric drawing (PDF) to the current project', specifying the verb (upload), resource (isometric drawing), format (PDF), and target (current project). It distinguishes from siblings like upload_document (generic) and upload_large_format_drawing (large format).
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 provides context for when to use the tool (uploading isometric PDFs) and explains the do_not_extract flag's purpose. It implicitly advises when to set the flag but doesn't explicitly mention when not to use or compare with other upload tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a large-format drawing (P&ID, plan, elevation, overview) PDF to the current project. Set do_not_extract=True to skip server-side AI extraction.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| do_not_extract | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses the ability to skip server-side AI extraction, but fails to mention potential side effects, error conditions, return values, or prerequisites (e.g., file path accessibility). Adequate but not detailed.
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 concise sentences with front-loaded purpose and key option. No waste; every word adds value.
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 covers the core purpose, file type, and extraction option. It could mention file size limits, format constraints, or return value structure, but given the presence of an output schema (not shown), the omission is acceptable.
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 must compensate. It adds meaning for do_not_extract (skip extraction), but file_path is only described by name and as required. No additional semantics for file_path, resulting in partial coverage.
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 clearly states the tool uploads large-format drawings (P&ID, plan, elevation, overview) as PDFs to the current project, which distinguishes it from siblings like upload_document and upload_drawing. The verb 'upload' and specific resource types are 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?
The description provides context for when to use (large-format drawings) and explains the optional do_not_extract parameter. It does not explicitly state when not to use or mention alternatives, but the purpose is clear enough for basic guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0attach_photoauth_statuscomplete_form_submissioncreate_form_submissioncreate_map_itemcreate_notecreate_referencecreate_reference_requestdownload_fillable_templateget_active_projectget_documentget_fillable_templatelist_document_folderslist_documentslist_fillable_templateslist_form_submissionslist_itp_line_itemslist_list_itemslist_listslist_map_item_schemaslist_map_itemslist_noteslist_project_memberslist_projectslist_reference_requestslist_referenceslist_tenantsloginlogoutmark_itp_acceptedmark_itp_completemark_map_item_acceptedmark_map_item_completeresolve_noteset_document_extracted_dataset_projectsubmit_fillable_templateturnover_reportupload_documentupload_drawingupload_large_format_drawingMost tools target distinct resources and actions, with clear descriptions. A few pairs like upload_document/upload_drawing/upload_large_format_drawing could cause minor confusion, but overall boundaries are clear.
The majority follow a consistent verb_noun pattern (list_projects, create_note, upload_document). Exceptions like auth_status, get_active_project, and turnover_report are minor deviations.
41 tools is on the higher end, but the domain (QC database with multiple entity types and workflows) justifies many of them. Still, the count feels slightly heavy for an MCP server.
The toolset covers core CRUD and lifecycle operations for documents, map items, ITP items, notes, forms, and references. Missing explicit delete/update tools for some entities, but status changes and completions are present.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connects AI assistants to CloudQuell multi-cloud and AI cost, savings, anomaly, and budget data.
No-code databases, forms, portals and AI sites. Manage records and automation via natural language.
No-code databases, forms, portals and AI sites. Manage records and automation via natural language.
No-code databases, forms, portals and AI sites. Manage records and automation via natural language.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ProcessQualitySolutions/qcdatabase_mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
