AIR MCP Server

by VericyIO

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.1
Disambiguation5/5
Each tool targets a distinct action or resource: project CRUD, document upload/extraction, artifact retrieval, assessment lifecycle, domain listing, and combined workflows. No two tools have overlapping purposes.
Naming Consistency5/5
All tools follow the 'air_verb_noun' pattern consistently. Verbs like list, get, create, upload, start, wait, run clearly indicate the action, and nouns like project, document, assessment, domain specify the resource.
Tool Count4/5
With 25 tools, the server covers a complex risk assessment workflow comprehensively. While on the higher end, each tool serves a distinct need, and the count is justified by the domain's depth.
Completeness4/5
The tool surface provides full lifecycle coverage for domains, projects, documents, artifacts, and assessments, including upload, extraction, assessment start, waiting, and reporting. Minor gaps like missing project update/delete are acceptable for a read-heavy risk assessment API.
Average 3.9/5 across 25 of 25 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 22 commits in the last 12 weeks
- Last stable release on July 27, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it lists 'summaries' (not full assessments) and requires 'assessments:read' permission. This adds some context beyond annotations, but doesn't detail return format or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. The first sentence immediately states the core action. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is insufficiently complete. It fails to describe the parameter or provide details about the return structure (assessment summaries). Annotations cover safety but behavioral details are sparse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter (projectPid) with 0% description coverage, and the description does not mention or explain it. The name 'projectPid' is self-explanatory as a project ID, but the description provides zero parameter guidance. Given 0% coverage and no additional info, the score is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists assessment summaries for a project. The verb 'list' and resource 'assessment summaries' are specific. However, it doesn't differentiate from sibling tools like air_get_assessment (which gets a single assessment) or other list tools, but the context of 'assessment summaries' provides distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a permission requirement ('Requires assessments:read') but no guidance on when to use this tool versus alternatives like air_get_assessment or air_list_assessment_stages. No explicit when-not-to-use or context hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds the condition 'for a completed run', implying the tool may fail or return empty if the assessment is not completed. It also states 'Requires assessments:read', which is a permissions context. This adds some value beyond annotations, but not a full disclosure of behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the core purpose efficiently. It is front-loaded and avoids fluff. However, it could include a bit more detail without becoming verbose, such as mentioning the structure of the report.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and annotations present, the description covers the basic purpose and a key requirement (completed run). However, it does not mention return format details, error scenarios, or how it differs from `air_get_assessment` (which is a sibling). It is minimally complete but leaves questions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter `assessmentPid` has no description in the schema (0% coverage) and the tool description does not explain it. There is no format, example, or clarification of what it represents (e.g., project ID, assessment ID). The name alone is insufficient for an agent to correctly provide the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch', the resource 'structured risk assessment report JSON', and the condition 'for a completed run'. This distinguishes it from siblings like `air_get_assessment` which likely returns a summary, and `air_get_assessment_stages` which returns stages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks guidance on when to use this tool vs alternatives. It only mentions a permission requirement but no explicit when/when-not or comparison to siblings. For example, it doesn't clarify that this returns the full JSON report, while `air_get_assessment` might return a different format.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. Description adds the domain-scoped key constraint, but lacks details on response structure, error conditions, or other behavioral traits beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the purpose and immediately follow with key constraints. No superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite simple input schema and annotations, the lack of output schema means the agent needs description to infer return format. The description offers only purpose and auth, not enough to fully understand the tool's output or behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; description does not explain the parameters 'orgSlug' and 'domainSlug' beyond the tool's domain context. No format, allowed values, or examples are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Domain-level portfolio dashboard,' specifying a distinct verb and resource. It differentiates from siblings like 'air_get_domain' and 'air_list_domains' by focusing on the portfolio scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides context on required permission ('portfolio:read') and API key scope, but does not explicitly guide when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds permission requirement 'Requires projects:read' beyond annotations, which already indicate safe read. No contradiction; annotation support is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description doesn't mention pagination, limits, or artifact structure. Provides usage hint but lacks parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, and the tool description does not explain what projectPid or includeArchived mean. Agent must infer from names. Description should compensate but fails.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List document-derived artifacts for a project' with specific verb and resource. However, doesn't differentiate from sibling tools like air_list_documents or air_get_artifact_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions using artifact pids in air_start_assessment, providing downstream context, but does not specify when to use this tool instead of alternatives or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description adds key behaviors: credit consumption, pipeline dispatch, auth requirement, and return value. This complements the readOnlyHint=false and openWorldHint=true. However, it does not mention idempotency or failure handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each delivering distinct value: purpose, side effects/cost, auth/return. No redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key aspects but omits important context: the async nature of the pipeline, that air_wait_for_assessment should be used afterward, and the source of projectPid (from air_list_projects/air_get_project). Given the moderate parameter count and lack of output schema, more completeness would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (2 of 3 params have descriptions). The description adds source context for artifactPids and purpose for name, but the projectPid parameter is left unexplained. The tool description does not fully compensate for the missing schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it starts a risk assessment on a project, with specifics like consuming credits and dispatching a pipeline. However, it does not explicitly differentiate from sibling tools like air_run_assessment_from_file or air_run_full_assessment_pipeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates a required permission (assessments:write) but provides no when-to-use guidance or alternatives among siblings. It implies using air_list_artifacts first but does not state prerequisites or the proper sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false, so the description adds the permission requirement as extra context. But it lacks details on pagination, error behavior, or response structure. The openWorldHint is not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences: first describes the action, second states the required permission. No redundant or unnecessary content. It is efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single required parameter and no output schema, the description is minimally complete. However, it could benefit from clarifying the response format or providing an example. Sibling tools add complexity that is not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the parameter 'assessmentPid'. The description does not explain its format, expected values, or how to obtain it. The only addition is the permission requirement, which does not compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'artifacts used as inputs when the assessment report was generated'. It distinguishes from sibling tools like air_list_artifacts (all artifacts) and air_get_assessment_report (the report itself) by specifying the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the required permission 'assessments:read', giving a usage condition. However, it does not explicitly contrast with alternative tools like air_list_artifacts or explain when to prefer this tool. The usage context is implied but not guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-destructive read operation (readOnlyHint, destructiveHint). The description adds the permission requirement 'assessments:read', which is valuable and consistent with annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, extremely concise. However, it sacrifices some detail that could be added without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fails to describe what the tool returns (e.g., list of logs, structure). The single parameter is not well explained, and there is no mention of pagination or other details that would aid the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description only implicitly suggests that 'assessmentPid' identifies the assessment run. It does not explain the format or expected values, leaving the agent with minimal guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), resource ('per-stage checkpoint logs'), and context ('for an assessment run'), effectively distinguishing it from sibling tools like air_get_assessment or air_get_assessment_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing checkpoint logs and mentions required permission, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the bar is lower. The description adds that the tool requires 'assessments:read' scope, providing valuable permission context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second states requirement. No fluff, front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions the tool returns status and workflowRunId but does not specify the full response format. Since there is no output schema, the description should fully describe the return value; it only partially does so.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description 'Assessment pid (pasm_*)' is already provided in the schema. The description adds no further meaning or constraints for the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool gets assessment detail including specific fields like status and workflowRunId, which distinguishes it from sibling tools like air_get_assessment_report and air_get_assessment_stages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., air_list_assessments for listing or air_get_assessment_report for report). The only requirement is permissions, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false) already indicate a safe lookup. The description adds no further behavioral details (e.g., error handling, what happens if not found, idempotency). It is consistent with annotations, so no contradiction, but adds minimal value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose, no redundancy. Every word is necessary and informative. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters and no output schema, the description covers the two resolution patterns but lacks details on return format, conflict handling (if both pid and slugs provided), or error conditions. Adequate for basic understanding but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only projectPid has a description). The description adds clarity by explaining the two usage paths (pid vs. slugs), but does not describe each parameter's role or constraints beyond what the schema provides. Partial compensation for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'resolve' and resource 'project', and specifies two resolution modes (by pid or by slugs). It effectively distinguishes from siblings like air_list_projects by mentioning the pid source. However, the term 'resolve' could be more explicit (e.g., fetch details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use: when you have a pid from air_list_projects or a combination of orgSlug/domainSlug/projectSlug. It implies not to use without these identifiers. However, it does not mention when not to use alternatives or provide exclusion criteria for sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is read-only and non-destructive. The description adds the relevant permission requirement ('projects:read'), which is behavioral context not captured by annotations. No contradictions or misleading statements are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single, clear sentence and an added permission note. Every word serves a purpose, and there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description implies the result is plain text, but it does not specify the format, structure, or any potential error conditions. The simplicity of the tool (2 params) reduces the need for extensive detail, but additional output context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema description coverage, only `artifactPid` has a brief description ('Artifact pid (artf_*)'), while `projectPid` lacks any description. The tool description does not elaborate on parameter meanings or usage, relying heavily on the schema which is partially undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('extracted plain text for an artifact'). It distinguishes from sibling tools, such as `air_get_document_download_url` (which provides URLs) and `air_list_artifacts` (which lists artifacts), by focusing on retrieving the text content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a permission prerequisite ('Requires projects:read'), which is helpful. However, it does not specify when to use this tool versus alternatives like `air_list_artifacts` or `air_get_document_download_url`, nor does it provide scenarios where this tool is not appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, indicating safe, read-only operation. The description adds the specific permission requirement (projects:read), which is valuable beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence stating purpose and a second sentence for permission requirement. It is front-loaded with the key action and avoids superfluous details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 required params, no output schema). The description explains purpose and permission but does not mention what the return value looks like (e.g., a URL, its format, expiration). Given no output schema, describing the return would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema description coverage (sourcePid described, projectPid not), the description adds no extra parameter information. It mentions 'document source' but does not explain projectPid or provide guidance on valid values. The description should compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a presigned download URL for an uploaded document source, using specific verb and resource. It distinguishes from siblings like air_list_documents (list) and air_upload_document_init (upload) by focusing on URL retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the required permission (projects:read) but does not provide explicit guidance on when to use this tool versus alternatives (e.g., air_list_documents for metadata). It implies usage when a download URL is needed, but lacks when-not or exclusion hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's mention of polling adds some extra context about expected behavior before proceeding. However, it does not disclose other behavioral traits like pagination, rate limits, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, no wasted words. First sentence states purpose, second adds usage hint and permission requirement. Perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two parameters and no output schema, the description provides adequate context: what it does, how to use it (polling), and required permission. It could be improved by mentioning response structure, but it's fairly complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond what the schema provides, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List document sources for a project' with a specific verb and resource. It adds context about polling for status, which distinguishes the tool's purpose from siblings like air_list_artifacts. However, it doesn't explicitly differentiate from other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage guideline: 'Poll until status is connected before starting an assessment.' It also states the required permission 'projects:read.' However, it does not mention when not to use this tool or list alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant value beyond annotations: it discloses credit consumption, immediate task handle return, and polling requirement. Annotations (readOnlyHint=false) already indicate mutation, but the description enriches transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose, no wasted words. Each sentence delivers essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no parameter descriptions, the tool's context is incomplete. Missing details on error handling, timeout behavior, and the report summary structure hinder proper invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation for any of the 4 parameters. For a tool with multiple parameters including arrays and integers, this leaves agents guessing about expected values and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (start, wait, return) on specific resources (existing artifacts, assessment pipeline) and distinguishes from siblings like `air_start_assessment` and `air_wait_for_assessment` by combining start and wait.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it consumes credits and returns a task handle for polling. It implicitly tells when to use (full pipeline run) but does not explicitly mention alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show readOnlyHint=false and destructiveHint=false; description adds behavioral context by stating it requires a write permission and does not start the pipeline. This goes beyond annotations and clarifies the tool's non-destructive yet write-requiring nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence conveys purpose and a key constraint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and description does not mention return values. It covers permission and scope but leaves the response behavior implicit. Adequate for a simple create action but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (projectPid lacks description). The tool description does not add any extra meaning to parameters beyond what the schema provides. For a moderate coverage, description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create an assessment draft without starting the pipeline' with a specific verb and resource. It distinguishes from sibling tools like air_start_assessment and air_run_full_assessment_pipeline by emphasizing it does not start the pipeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'without starting the pipeline,' indicating when to use this tool (draft only). It also notes the required permission 'assessments:write.' While it does not explicitly list exclusions or alternatives, the sibling tools provide context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only and not destructive. The description adds critical behavioral details: the required permission and that it returns 'project pid and slug'. For a creation tool, this adequately discloses key traits beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence containing all essential information: action, target, permissions, and return values. No extraneous words or repetition, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter creation tool with no output schema, the description covers the main inputs, outputs, and permission requirements. It could mention that 'description' is optional, but overall is sufficiently complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% parameter description coverage, with each parameter documented clearly. The description does not add additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Create a project in a domain.' It clearly distinguishes from sibling tools which are mostly retrieval or assessment-related, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states required permissions ('Requires domains:write (fullPipeline preset)'), which is useful context, but lacks explicit guidance on when to use this tool versus alternatives (e.g., when to create vs list projects). No when-not or alternative comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool requires 'assessments:write' permission and consumes credits, adding behavioral context beyond annotations (readOnlyHint=false, destructiveHint=false). This helps the agent understand side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with an additional requirement clause, front-loading the essential purpose and constraints without extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers purpose and non-obvious side effects but lacks parameter documentation, which is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'assessmentPid' is not described in the description; with 0% schema coverage, the agent receives no guidance on what value to provide, reducing usability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retry a failed assessment from the last completed stage', specifying the verb (retry) and resource (assessment), and distinguishes from siblings like 'start_assessment' or 'create_assessment_draft'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is for retrying failed assessments and mentions required permissions and credit consumption. However, it does not explicitly contrast with alternatives like re-running the full pipeline or fixing issues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that it dispatches a document extraction workflow, a side effect not in annotations. It also states required auth scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action. Every sentence adds value, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes the finalization step and workflow dispatch, but with no output schema, it should clarify what the tool returns (e.g., document ID). Lacks completeness for a multi-step tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (25%). The description only adds context for s3Key (links to init), but no other parameters are explained. Fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finalizes a presigned upload after PUT, and dispatches extraction workflow. It distinguishes from siblings like init and wait, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells when to use: after air_upload_document_init (by referencing the storage key). It mentions required permission (projects:write), but lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the description adds value by detailing polling states, timeout behavior, and exponential backoff. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each adding essential information. No redundancy or fluff. The critical details (polling, states, timeout, backoff, task handle) are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a polling tool with two params and no output schema, the description covers key behavioral aspects like states, timeout, backoff, and the task handle pattern. It could explain how to use the task handle (e.g., 'poll tasks/get') but that is referenced succinctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with only timeoutMs described. The description does not add any parameter context, leaving the required 'assessmentPid' undocumented. This is a significant gap for a tool with two parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it polls 'air_get_assessment' until specific states (completed, failed, reportAvailable) or timeout, and returns a Task handle. This distinguishes it from sibling tools that are direct actions or retrieval, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions exponential backoff per async-jobs guidance, implying standard usage. While it doesn't explicitly state when not to use it, the context is clear that it's for waiting on assessment completion, differentiating it from synchronous alternatives like 'air_get_assessment'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations (readOnlyHint, openWorldHint) by specifying the two resolution methods and the data source (air_list_domains results). It is consistent with the read-only nature and provides useful behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core purpose and efficiently conveys both lookup methods. No unnecessary words, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with three optional parameters and no output schema, the description fully covers the necessary context: two lookup paths, data source, and parameter relationships. Nothing is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, but the description adds meaning by linking domainPid to air_list_domains and pairing orgSlug with domainSlug. This extra context justifies a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (resolve) and resource (domain) with two distinct lookup methods: by pid from air_list_domains results, or by orgSlug + domainSlug. It does not explicitly differentiate from sibling tools, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage after air_list_domains (via pid) or via slugs, providing clear context for when to use each method. It lacks explicit exclusion statements or alternative tool references, but the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description correctly focuses on additional behavioral context: the required scope for authorization. This adds value without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each providing essential information: the core function and a key usage constraint. No redundant words; structure is front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 100% schema coverage and presence of annotations, the description is largely complete. It covers purpose and authorization scope. Minor gap: no hint about response format or pagination, but not critical for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptive parameter names and comments. The description does not add extra meaning beyond 'full-text search', which is aligned with the schema. Baseline score of 3 is appropriate as no additional parameter details are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'full-text search across orgs, domains, and projects', which is a specific verb and resource. It distinguishes from sibling tools that focus on individual entities (e.g., air_list_projects, air_get_domain) by emphasizing cross-entity search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes the required scope ('search:read scope') and notes it's part of 'fullPipeline preset' but not in 'assessmentRunner', giving context on when the tool can be used. It does not explicitly mention alternatives or when not to use it, but the siblings provide implicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it indicates that the tool returns uploadUrl and s3Key, and that it is part of a two-step process. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences, with essential information front-loaded. No redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential workflow and return values. Lacks details about presigned URL expiration or file size limits, but overall sufficient given the tool's role in a multi-step process.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 67% of parameters with descriptions. The tool description does not add detail about filename or contentType, but implies projectPid is needed via the permission requirement. Baseline 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: to start a presigned upload, returning uploadUrl and s3Key. It differentiates from siblings by specifying the workflow and naming the completion tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It instructs to PUT file bytes to uploadUrl and then call air_upload_document_complete, providing clear context for use. It also mentions required permission (projects:write), but does not exclude scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint true and destructiveHint false. The description adds behavioral details: polling mechanism, return of an MCP Task handle, polling tasks/get, exponential backoff, and timeout. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with the core action and condition. Efficiently conveys the purpose and key behaviors.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a polling tool with no output schema, the description covers the polling process, task handle, timeout, and backoff. It is sufficiently complete given the complexity and rich annotations. Could optionally detail what the final result contains, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 33% with only timeoutMs having a description. The description explains sourcePid's role (status to reach) and mentions timeoutMs default (600000ms) and the polling condition. However, projectPid is not described. The description partially compensates for the low coverage but does not fully document all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool polls until a condition (sourcePid reaches connected or error) or timeout. It specifies the action (poll air_list_documents), resource (document extraction status), and scope (per sourcePid). This distinguishes it from sibling tools like air_wait_for_assessment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it (to wait for extraction completion) and mentions using exponential backoff per async-jobs guidance. It provides clear context but does not explicitly state when not to use it or list alternatives, though the polling mechanism is well-described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds behavioral details: required permissions and pagination behavior (page, pageSize). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The first sentence states purpose and pagination; the second gives permissions and a cross-reference. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description covers permissions, pagination parameters, and domainPid sourcing. Lacks details about return format (e.g., list of project objects with fields), but given the simplicity of the tool, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds value by linking domainPid to air_list_domains, which helps the agent understand provenance. Otherwise, parameters are well-documented in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('projects'), and the scope ('in a domain'), and mentions pagination. This distinguishes it from siblings like air_get_project (single project) and air_list_domains (list domains).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies required permissions ('domains:read and projects:read') and gives a cross-reference hint ('Use domainPid from air_list_domains'). It does not explicitly state when not to use or mention alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by specifying the required 'domains:read' scope and the special behavior for domain-scoped service accounts. Annotations already confirm it's read-only and non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences that front-load the main action. Every sentence provides necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the absence of an output schema, the description fully covers what the tool returns (a list of domains, or a single domain for domain-scoped keys) and the prerequisites (scope). It is complete for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so no additional explanation is needed. The description adequately addresses the lack of parameters by describing the tool's behavior without requiring parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists domains visible to the API key, with a specific mention of domain-scoped service account keys. This differentiates it from sibling tools like air_get_domain, which likely retrieves a single domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to list all domains or the bound domain for domain-scoped keys), but does not explicitly compare to alternatives like air_get_domain. It does specify the required scope, which helps in usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description adds critical behavioral details: credit consumption, required permissions (projects:write, assessments:write), asynchronous return via an MCP Task handle, and file system access context ('Reads filePath with your OS user permissions'). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: four sentences front-loading the main action, followed by key constraints and return type. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multi-step process, 4 parameters, no output schema), the description adequately covers the workflow and immediate return (Task handle). It could be improved by hinting at the extraction duration or how to interact with the returned task (e.g., via air_wait_for_assessment), but it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema description coverage, the baseline is 3. The description adds value by clarifying that filePath is read with the agent's OS user permissions, going beyond the schema's description of 'Absolute or relative path'. Other parameters are adequately described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's actions: upload a local file, wait for extraction, start assessment on the new artifact. It uses specific verbs and resources, and the process is distinguishable from siblings like air_start_assessment (which starts on an existing artifact) and air_run_full_assessment_pipeline (which handles the entire pipeline differently).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides prerequisites (credit consumption, required permissions) and mentions that it returns an MCP Task handle immediately. However, it does not explicitly specify when to use this tool over alternatives, such as air_run_full_assessment_pipeline or air_start_assessment, which are available as siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mcp-air MCP server](https://glama.ai/mcp/servers/VericyIO/mcp-air/badges/card.svg)](https://glama.ai/mcp/servers/VericyIO/mcp-air)

Score Badge

Copy to your README.md:

[![mcp-air MCP server](https://glama.ai/mcp/servers/VericyIO/mcp-air/badges/score.svg)](https://glama.ai/mcp/servers/VericyIO/mcp-air)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/VericyIO/mcp-air'

If you have feedback or need assistance with the MCP directory API, please join our Discord server