Fetch the complete OpenAPI 3.0 specification for the HireSquire ecosystem. Use this when you need detailed documentation on REST endpoints or data models.
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "get_api_schema"
}
}| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Changes observed during successful MCP inspections.
Input schema / requiredAdded value: +[]Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full behavioral burden. It usefully discloses that the payload is the 'complete' spec, implying a large response, but says nothing about the serialization format (JSON vs YAML string), response size, caching, or any auth requirement for a documentation fetch. For a zero-risk read this is acceptable, but the disclosure is thinner than a 4 would require.
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 short sentences with zero filler. The capability is front-loaded in the first sentence and the usage trigger follows immediately in the second.
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 parameterless fetch whose return value is a standardized OpenAPI 3.0 document, the description gives enough context: version, scope, and purpose. The only real gap is the transport format and expected size of the returned specification, which matters for an agent deciding whether to pull the whole spec into 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 tool takes no parameters, so the schema cannot be improved upon and the baseline of 4 applies. The description correctly implies the call is unconditional with no filtering or version selection arguments.
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 verb and resource — 'Fetch the complete OpenAPI 3.0 specification' — with the scope ('complete') and target system ('HireSquire ecosystem') named. No sibling tool performs anything similar, so an agent can immediately distinguish this metadata tool from the operational tools like get_results or create_interview.
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 when to use it: 'when you need detailed documentation on REST endpoints or data models.' That is a clear trigger condition. It stops short of a 5 because it offers no counter-case or alternative routing (e.g. pointing to specific tools when the agent only needs one operation), but no obvious alternative exists among the siblings.
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.