Every player PSA ProBatFacts lists for one category, each with the numeric subject_id to pass to psa_probatfacts_subject for that player's full bat-authentication reference page. category_id is from psa_probatfacts_categories.
| Name | Required | Description | Default |
|---|---|---|---|
| CategoryID | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | The tool result payload (shape varies per tool; see each tool's docs resource). |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and open-world profile is covered. The description adds useful behavioral context about the ID handoff to the sibling tool, but says nothing about result size, pagination, or completeness of the listing.
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 dense sentences, front-loaded with what the tool returns, followed by the two ID-chaining facts. No filler and nothing to trim.
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-value explanation is unnecessary. For a one-parameter listing tool, the description covers the input source, the output identity (subject_id), and the downstream consumer, leaving no actionable gap.
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% and the schema only declares an opaque integer CategoryID with no description. The description compensates by telling the agent exactly where to source the value (psa_probatfacts_categories) and that it scopes the result to one category.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and scope ('Every player PSA ProBatFacts lists for one category') and distinguishes itself from the sibling psa_probatfacts_subject by naming that tool as the drill-down for a player's reference page. An agent can tell the list tool from the detail tool without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: category_id comes from psa_probatfacts_categories, and the returned subject_id is what you pass to psa_probatfacts_subject. This establishes the call chain clearly, though it doesn't state any when-not-to-use condition or pagination caveats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
