ACC.MCP

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it's a raw/power-user tool that returns full JSON responses, handles pagination, supports POST/PATCH methods, and covers endpoints not in simplified tools. However, it doesn't mention authentication requirements, rate limits, or error handling, leaving some gaps for a tool with such broad capabilities.

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 efficiently structured with zero waste: the first sentence states the core purpose, the second establishes its role versus alternatives, and the third provides specific usage guidelines with examples. The final sentences offer crucial implementation details about the base path and sub-path usage. Every sentence serves a clear purpose and is front-loaded with essential 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 complexity (5 parameters, no output schema, no annotations), the description does an excellent job covering purpose, usage guidelines, and parameter context. However, for a raw API tool with POST/PATCH capabilities, it could better address authentication needs, error responses, or response structure expectations. The lack of output schema means the description should ideally hint at what 'full JSON response' entails.

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 100%, so the baseline is 3. The description adds valuable context beyond the schema: it explains the base path structure ('construction/submittals/v2/projects/{projectId}/'), clarifies that only the sub-path after this is needed, and provides concrete examples of sub-paths (e.g., 'items', 'packages', 'specs'). This enhances understanding of how parameters work together in practice.

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 purpose: 'Call any ACC Submittals API endpoint' and identifies it as a 'raw / power‑user tool' that returns full JSON responses. It explicitly distinguishes this from simplified sibling tools like aps_list_submittal_items, aps_list_submittal_packages, etc., making the distinction clear and 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?

The description provides explicit guidance on when to use this tool versus alternatives: 'Prefer the simplified tools... for everyday use' and 'Use this tool when you need full control: pagination, POST/PATCH, or endpoints not covered by simplified tools.' It names specific use cases and clearly differentiates from sibling tools, offering comprehensive when-to-use and when-not-to-use advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.