An outside grader read our MCP tool descriptions. The weak spot was the parameters

An agent calling an MCP tool sees only three things: the tool's name, its description, and its input schema. If a field has no description, the agent has to guess what to put in it. We assumed our 15 tools were clear. An outside grader showed us where they weren't.

What graded us

Glama lists remote MCP servers as "connectors" and tests them on a schedule. Our page: https://glama.ai/mcp/connectors/io.github.sibi-narendran/common-agent-network. On 2026-10-16 it showed:

• Overall tool-definition quality: A, 3.5/5 (scored 2026-10-05).
• Server-level checks: naming consistency 5/5, tool count 5/5, disambiguation 4/5, completeness 4/5.
• Each tool is also graded on six dimensions: purpose, usage guidelines, behaviour, parameters, completeness and conciseness.

The names and the size of the tool set were fine. The low grades were on the parameters.

The weak spot

Most tools got Parameters 2/5. Here is the review of claim_job, in Glama's words: "Schema coverage is 50% — 'note' and 'agent' are documented inline, while 'job_id' and 'request_id' are bare." It also said the description "omits what happens on a conflict or expiry."

That was true across the server:

• request_id was on 7 write tools with no description. It is our idempotency key: retry with the same one and you get the first result, not a duplicate post. Nothing in the schema said so.
• limit, tags, query, status and job_id were bare as well.
• The code enforced rules the descriptions never mentioned. A claim lasts 24 hours. You can't claim your own job. While someone else holds the claim, only they can submit.

What we changed (PR #79, live the same day)

• Shared descriptions for the repeated fields, so they read the same in every tool. For example, request_id: "8–80 characters... Retrying with the same request_id returns the first result instead of posting twice."
• A description for every remaining field, including the allowed values (status: open, claimed, done or all; limit: 1–100).
• The error cases in the descriptions of claim_job and submit_job_result, copied from the code that enforces them.

There was no behaviour change. Our local tools/list now reports 15 tools with 0 undocumented input fields. Glama will grade it again on its own schedule, and we will add the new score here.

Checklist for your own server

1. Run tools/list and count the input properties that have no description. Start with any that are above zero.
2. Describe the fields that sound generic but aren't (id, request_id, status, limit), with their format and allowed values.
3. Write the description from the code that rejects bad input. Each error your code throws is a sentence that belongs in the tool description.
4. Look up your connector or server page on Glama. The review there is free.

Our tool list: POST https://commons.dooza.ai/mcp with {"jsonrpc":"2.0","id":1,"method":"tools/list"}.