ACC MCP

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

With no annotations provided, the description fully discloses side effects (persistent issue record), idempotency (NOT idempotent, dedupe by title), rate limits, and detailed error semantics (401, 403, 404, 422, 429, 5xx). This is comprehensive and goes beyond basic expectations.

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 well-structured with clear headers (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects). Every sentence provides actionable information; it is long but not bloated, and the front-loaded purpose ensures the agent immediately knows what the tool does.

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 tool has no output schema, so the description should ideally cover return behavior. It comprehensively covers authentication, rate limits, error handling, and side effects, but does not explicitly state what the API returns (e.g., created issue ID). This is a minor gap given the otherwise rich 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 input schema already covers 100% of parameters with examples and descriptions, so baseline is 3. The description adds extra value by clarifying the 'b.' prefix requirement for project_id and noting that the worker strips it internally, which is not in the 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 starts with a specific verb ('Create a new ACC issue') and identifies the resource and API. It also lists example issue types, distinguishing it from siblings like acc_create_rfi and acc_update_issue.

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 includes explicit 'When to use' and 'When NOT to use' sections, with concrete examples and named alternatives (acc_update_issue for modifications, acc_create_rfi for RFIs). This leaves no ambiguity about when the tool should be selected.

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

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

With no annotations, the description carries the full burden and excels: it discloses side effects (persistent record, NOT idempotent, duplicate risk), authentication scopes, rate limits (specific numbers), and a comprehensive error breakdown with causes and actions. This far exceeds typical descriptive 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 long but every sentence delivers actionable information. It uses clear labeled sections (When to use, When NOT, APS scopes, Rate limits, Errors, Side effects) that make scanning efficient. No filler or redundant phrasing exists.

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 purpose, usage boundaries, errors, side effects, rate limits, and scopes comprehensively. However, it omits what the API returns on success (e.g., created RFI ID), which is notable for a creation tool without an output schema. Minor but significant 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 100%, so the baseline is 3. The description adds minimal parameter-specific value beyond the schema: error messages tie 422 to missing subject/question or invalid priority, and dedupe advice references subject. However, this context is peripheral; most semantic details already exist in the 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 explicitly states the action ('Create a new Request For Information (RFI)'), the target resource ('ACC project via the APS Construction RFIs API'), and distinguishes from sibling tools by specifying the draft status and workflow ownership. It clearly differentiates from acc_create_issue via the when-not-to-use guidance.

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?

Contains explicit 'When to use' and 'When NOT to use' sections with concrete examples ('raise an RFI asking for clarification...') and alternative tool names (acc_create_issue). It also states limitations ('answer an existing RFI... not supported here'), providing complete guidance on appropriate invocation.

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

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

With no annotations provided, the description takes full responsibility for behavioral disclosure. It states 'Side effects: None. Read-only and idempotent', explains required scopes, rate limits, pagination behavior, and enumerates possible errors (401–5xx) with remedies. This is thorough and leaves no critical ambiguity.

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?

Although long, the description is structured into clear, labeled sections (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects). Every section conveys independent, useful information; nothing is redundant. The core purpose is front-loaded in the first sentence.

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 read-only list/filter tool with no output schema and no annotations, this description is highly complete. It covers use cases, alternatives, scopes, rate limits, error handling, side effects, pagination, and even the peculiarity of the assigned_to filter. It provides everything an agent needs to invoke the tool correctly and handle failures.

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 100%, so the baseline is 3. The description adds context about the 50-per-call limit and filtering, but parameter-specific meaning is already fully covered by the schema (e.g., the assigned_to parameter's caveat is in the schema itself). The description does not materially enhance parameter semantics beyond what the schema provides.

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 opens with a clear, specific verb-object pairing: 'List and filter issues from a single ACC project (limit 50 per call)'. It explicitly distinguishes from siblings by stating 'Do not use to fetch RFIs (use acc_list_rfis) or to search documents', making its scope unambiguous.

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?

A dedicated 'When to use' section provides specific scenarios (review open issues, count by status/priority, look up issue_id) and a concrete example. A 'When NOT to use' section explicitly names alternative tools (acc_list_rfis, acc_search_documents), meeting the highest standard for usage guidance.

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

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

With no annotations, the description fully discloses behavior: required APS scopes, rate limits (50 req/min, pagination), fan-out pattern (1 hubs call + N project calls), specific error codes with remediation (401, 403, 404, 429, 5xx), and side effects (none, read-only, idempotent). This goes far beyond what annotations would provide.

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 appropriately sized for the tool's complexity, with clear section labels (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects). Every sentence provides actionable information without fluff, and the most critical usage guidance is front-loaded.

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 having no output schema, the description is complete for an agent to decide when to call this tool and what to expect. It covers prerequisites, error handling, performance pitfalls (fan-out, rate limits), and side effects. The only minor omission is the exact return shape, but the purpose and usage are sufficiently clear.

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 zero parameters, so the baseline is 4. The description adds meaning by explaining why no parameters are needed (walks all accessible hubs automatically), which is implicit but helpful.

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 with a specific verb ('Enumerate every ACC and BIM 360 project') and resource ('projects'). It also specifies the scope ('all accessible hubs'), which differentiates it from sibling project-specific tools that require a known project_id.

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 provides when-to-use (discovery of project IDs before other calls) and when-not-to-use (skip if project_id starts with 'b.', avoid repeated calls, cache results). Names alternatives by implication (any tool needing a project id) and gives clear exclusions.

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

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

With no annotations provided, the description carries the full burden and does an excellent job: it declares read-only and idempotent behavior, no side effects, required APS scopes (data:read, account:read), rate limits, pagination limits, and per-error-code details. This goes far beyond typical tool descriptions.

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?

Although the description is somewhat long, it is well-structured with labeled sections (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects). Every sentence carries useful information, and the core purpose is front-loaded in the first sentence.

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 thoroughly covers operational context: scopes, rate limits, pagination, error handling, and side effects. However, since there is no output schema, it does not explicitly describe the return format or fields of the RFI list, which would be useful for an agent to fully anticipate the response.

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 a minor note about the 'b.' prefix for project_id in the error section and confirms status is optional, but it does not substantially expand on the parameter semantics already present in the input 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 opens with 'List and filter RFIs from a single ACC project (limit 50 per call)', which clearly specifies the action, resource, and scope. It also explicitly distinguishes itself from sibling tools by stating 'Do not use for issues (use acc_list_issues) or document search (use acc_search_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?

A dedicated 'When to use' section provides concrete examples like reviewing open RFIs or counting outstanding ones, and a 'When NOT to use' section names alternatives (acc_list_issues, acc_search_documents). This gives explicit guidance on selecting the correct tool.

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

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

With no annotations provided, the description carries full burden. It discloses read-only/idempotent behavior, side effects ('None'), error codes with meanings (401, 403, 404, 422, 429, 5xx), scopes required, rate limits, and a recommendation to cache. This is comprehensive and beyond what annotations would have covered.

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 organized into labeled sections (main use, when to use/not use, scopes, rate limits, errors, side effects) and front-loads the core purpose. Each sentence contributes unique operational guidance; no filler or redundancy exists despite the length.

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 2-parameter tool with no output schema and no annotations, the description covers all necessary operational context: purpose, usage criteria, error codes, rate limits, scopes, side effects, and fallback behavior. The minimal complexity is fully addressed, leaving no critical gap for an agent to invoke the tool 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?

The input schema already provides exhaustive descriptions for both parameters, including prefix requirements and hub selection fallback, giving 100% schema coverage. The tool description repeats this information but does not add new parameter-level meaning beyond what the schema states, so the baseline score of 3 applies.

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 opens with 'Fetch the full ACC project metadata record... for a single project via APS Data Management,' clearly identifying the verb (fetch), resource (project metadata record), and scope (single project). It explicitly contrasts with acc_list_projects in the 'When NOT to use' section, distinguishing itself from the closest sibling.

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 an explicit 'When to use' section ('the user asks tell me about project X') and a 'When NOT to use' section that names the alternative tool (acc_list_projects). This gives the agent clear decision criteria and excludes misuse.

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

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Side effects: None. Read-only and idempotent.', discloses required scopes ('data:read account:read, no write scope required'), rate limits (~50 req/min, pageable limit 200), and enumerates error codes with specific mitigation actions (401 refresh, 403 permission, 404 project ID checks, 422 simplify syntax, 429 back off 60s, 5xx retry with jitter). This comprehensive transparency goes well beyond a minimal 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?

The description is well-structured with labeled sections (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects) and front-loaded with the core purpose in the first sentence. Every section provides actionable information without filler, making it scannable despite its length.

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 purpose, usage, exclusions, scopes, rate limits, error handling, and side effects, which is remarkably thorough. However, it omits any description of the response format (e.g., what fields are returned for matching documents), which is significant given that no output schema is provided. This prevents it from being fully 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 100% coverage with descriptions and examples for all three parameters, so the baseline is 3. The description adds general context about file types (drawings, specs, submittals) and usage examples, but the schema already covers parameter-specific details like the 'b.' prefix requirement for project_id and query matching semantics. The added value is marginal.

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 opens with 'Full-text search the ACC Docs repository of a project for drawings, specs, submittals, and other files via the APS Data Management search endpoint,' which clearly defines the verb (search), resource (ACC Docs repository), and scope. The 'When NOT to use' section explicitly names sibling tools like acc_upload_file and issue/RFI tools, distinguishing this tool from alternatives.

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 devotes dedicated 'When to use' and 'When NOT to use' sections with concrete examples ('find the latest A-201 sheet') and explicit alternatives ('do not use to upload a file (use acc_upload_file); do not use to fetch issues/RFIs'). This provides clear decision boundaries and direct tool differentiation.

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

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

With no annotations provided, the description fully carries the burden. It discloses mutation side effects, idempotency (PATCH semantics, safe to retry), required APS scopes, rate limits, and a detailed error taxonomy with actionable remediation. This is exemplary 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 well-organized into short purposeful sections (purpose, when to use, when not, scopes, rate limits, errors, side effects). No fluff; every sentence adds operational value. Length is justified by the tool's complexity.

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 almost everything an agent needs: usage, prerequisites, side effects, and error handling. The only minor omission is an explicit statement of what the tool returns on success (since there is no output schema), but this is a small gap given the mutation-focused use case.

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 100% and each parameter already has a description. The description adds little beyond what the schema provides, though the error notes reinforce constraints like the 'b.' prefix on project_id. Baseline 3 is appropriate given the schema's completeness.

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 opens with a specific verb ('Patch') and names the resource ('existing ACC issue') and affected fields (status, priority, assignee, description). It explicitly distinguishes from creation and comment tools, making sibling differentiation 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?

Provides explicit when-to-use triggers (close/reopen/escalate/reassign/edit body), a typical agent flow (acc_list_issues → pick id → acc_update_issue), and clear exclusions (do not use for create or comments, which are not supported). This goes beyond vague guidance.

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

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

With no annotations provided, the description fully discloses side effects: creates a storage object, uploads bytes, creates a versioned item, and is NOT idempotent—retries may duplicate items. It also lists all relevant error statuses, authentication scopes, rate limits, and the unauthenticated GET behavior, leaving little hidden.

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 long but every sentence earns its place: flow overview, usage guidance, exclusions, scopes, rate limits, errors, and side effects are organized under clear headers. There is no redundant filler; the length is justified by the tool's complexity.

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 (4 parameters, no output schema, no annotations), the description covers all necessary context: prerequisites, error handling, retry caveats, and expected return value (item_id). It leaves no significant operational gap, making it fully contextual.

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 schema already provides 100% parameter coverage with descriptions and examples. The description adds value by reiterating key constraints in context (e.g., the 100MB practical limit for file_url, the 'b.' prefix requirement for project_id) and clarifies folder_path matching in the error guidance. This goes slightly beyond the schema's 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 opens with a specific verb+resource: 'Upload a file from a public source URL into an ACC project folder.' It then details the four-step APS flow, clearly distinguishing this tool from siblings like acc_search_documents or acc_create_issue. The purpose is unambiguous and actionable.

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 'When to use' and 'When NOT to use' sections, including concrete examples, exclusions (auth-gated URLs, existing files), and an alternative flow for large files. It also covers rate limits and error responses, giving the agent clear operational guidance.

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