Air Pipe

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

With no annotations, the description carries full burden. It reveals that config_yaml is base64-encoded and that deployment can be to staging/production. However, it omits behaviors such as success/failure responses, idempotency, or overwriting behavior, which are relevant for an AI agent.

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 a single sentence that effectively front-loads the primary action and encoding detail. While it could benefit from more structure (e.g., listing parameters), it remains concise and to the point.

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 complexity (6 parameters, optional deployment, no output schema or annotations), the description does not fully equip an agent. Many parameters are undocumented, and the deployment intent is vague. The description lacks enough context for proper tool invocation.

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 0%, so the description must compensate. It adds meaning for config_yaml (base64-encoded YAML) and hints at deploy_staging/deploy_production, but leaves role_uuid, permission, and organization_uuid unexplained. This is insufficient given the low schema coverage.

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 action (create) and resource (AirPipe configuration), specifies that config_yaml is base64-encoded YAML, and mentions optional deployment. It effectively distinguishes from siblings like create_module, delete_config, and update_config.

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 mentions optional deployment but does not provide explicit guidance on when to use this tool versus alternatives like update_config or deploy_config_revision. The context of sibling tools suggests a need for clearer differentiation, but the description does not address it.

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?

No annotations are provided, so the description must fully disclose behavioral traits. It only explains two parameters but fails to mention what happens on duplicate handle, auth requirements, rate limits, or side effects of deployment.

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 two sentences, front-loaded with the core purpose and key parameter details. No wasted words.

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 9 parameters, no output schema, and no annotations, the description is incomplete. It lacks return value info, prerequisites, error conditions, and examples.

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?

With 0% schema description coverage, the description explains spec_yaml (base64-encoded YAML) and module_type (config struct), but ignores 7 other parameters (handle, role_uuid, permission, etc.), leaving them undocumented.

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 creates a reusable module with optional deployment, using specific verbs and resource ('Create a reusable module'). It distinguishes from sibling tools like create_config by specifying 'module' and 'optionally deploy'.

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 implies usage for creating modules with optional deployment but does not provide explicit when-to-use or when-not-to-use guidance relative to siblings like create_config or edit_module.

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?

No annotations exist, so description carries full burden. It indicates destruction ('Delete') but does not disclose whether deletion is permanent, required permissions, effects on related data, or rollback options. Minimal transparency for a destructive operation.

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?

Single sentence, front-loaded, no extraneous words. Minor imprecision ('config_uuid' vs 'config_uuids') prevents a perfect score.

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 no annotations, no output schema, and a destructive tool, the description is too brief. It lacks details on return values, success/failure indicators, error conditions, or post-conditions, making it incomplete for reliable agent use.

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 0%, so description must compensate. It mentions 'config_uuid' but parameter is 'config_uuids' (array). No explanation of what config_uuid is or how to obtain it. The required organization_uuid is not mentioned. Adds little meaning beyond schema names.

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?

Description states action ('Delete'), resource ('AirPipe configurations'), and criterion ('by config_uuid'). It distinguishes from siblings like edit_config. However, it says 'config_uuid' while the parameter is plural 'config_uuids', causing slight imprecision.

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?

No guidance on when to use this tool versus alternatives like undeploy_config or delete_module. No prerequisites, exclusions, or context for appropriate invocation are provided.

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?

No annotations provided, so description carries full burden. It does not disclose behavioral traits such as irreversibility, effects on deployed revisions, or dependency checks. Minimal information.

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?

Single sentence, concise and to the point. Could add a bit more structure but no wasted words.

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?

No output schema or annotations; description is minimal. Does not cover return values, error cases, prerequisites (e.g., module must exist), or consequences. Incomplete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, requiring description to compensate. Description mentions 'by module_uuid' but does not explain module_uuids parameter (array) or organization_uuid. Lacks format, constraints, or relationships.

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?

Description clearly states the action (Delete), resource (reusable modules), and method (by module_uuid). Distinguishes from sibling tools like undeploy_module which likely undeploys without deleting.

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?

No guidance on when to use this tool versus alternatives like undeploy_module or update_module. The description implies usage for deletion but lacks explicit context or 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?

No annotations provided. Description only says 'deploy' without disclosing whether it is destructive, reversible, or affects other configurations. The behavioral impact is unclear.

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?

Single sentence, no redundancy. However, the description is too brief to be useful; conciseness should not come at the expense of missing critical details.

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 no annotations, no output schema, and no parameter descriptions, the description is severely incomplete. The agent cannot determine what the parameters are or what deploying entails.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for 3 parameters. Description adds no information about what config_uuid, revision_uuid, or organization_uuid represent or their expected values.

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?

Description clearly states verb 'Deploy' and resource 'specific past revision of a configuration', with targets 'staging or production'. It is specific but does not differentiate from sibling tools like deploy_module_revision, which might cause ambiguity.

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?

No guidance on when to use this tool versus alternatives (e.g., plan_config, deploy_module_revision). No context about prerequisites 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.

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

With no annotations provided, the description should disclose behavioral traits. It states 'deploy' which implies mutation, but does not describe whether previous deployments are overwritten, permissions required, rollback capabilities, or potential destructive effects. This is a significant gap for a deployment action.

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 a single clear sentence with no fluff. However, it could include more details without sacrificing conciseness, e.g., destination environment explanation.

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 simple tool with 3 UUID params and no output schema, the description covers basic purpose but lacks behavioral context and parameter details. Agents may need to know about idempotency or deployment lifecycle, which is absent.

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 0%, yet the description only mentions 'specific past revision' without explaining what each UUID parameter represents or how they relate (e.g., organization_uuid identifies the organization). It adds minimal value beyond the parameter names.

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 verb 'deploy' and the resource 'specific past revision of a module', with target environments 'staging or production'. It distinguishes from sibling tools like 'deploy_config_revision' which targets a different resource.

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 mentions deploying a 'specific past revision' but offers no guidance on when to use this tool vs alternatives like 'deploy_config_revision' or prerequisites (e.g., module must exist, revision must be valid). No when-not-to-use context is provided.

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 bears full responsibility for behavioral disclosure. It only mentions editing with a natural-language instruction, but does not explain whether the tool modifies the configuration directly, requires authorization, or has side effects. The behavioral impact is unclear.

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 a single short sentence, making it concise but lacking necessary detail. It is not verbose, but it could be restructured to include essential information without sacrificing brevity.

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 (natural-language editing of YAML) and the absence of an output schema, the description is critically incomplete. It does not explain return values, error handling, or how the instruction is processed, leaving the agent with significant ambiguity.

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 0%, and the description provides no information about the three parameters ('instruction', 'current_yaml', 'organization_uuid'). The agent must infer their usage from context alone, which is insufficient.

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 edits an AirPipe configuration YAML using a natural-language instruction. It specifies the verb and resource, but does not differentiate from the sibling tool 'update_config', which may have overlapping functionality.

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?

No usage guidance is provided. The description does not indicate when to use this tool versus alternatives like 'update_config', nor does it mention any prerequisites or context where the tool should or should not be used.

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?

No annotations provided, so the description carries the burden. It indicates a read operation ('Get'), but lacks details on behavioral traits like whether revisions are returned by default, authentication needs, or side effects. The description is too brief.

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 a single, concise sentence that communicates the core purpose and key optional behavior. Every word earns its place with no fluff.

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 simplicity (get by ID), no output schema, and minimal annotations, the description is adequate but not thorough. It covers the basic purpose but misses details on return format, error scenarios, and revision behavior.

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 0%, so the description must compensate. It mentions 'by config_uuid' but does not describe the 'organization_uuid' parameter or add any format or meaning beyond the schema. The optional 'with its revisions' is a behavioral note, not parameter-level detail.

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 'Get a single configuration's data' using a specific verb and resource, and distinguishes from sibling tools like create_config, delete_config, and list_configs. The optional 'with its revisions' adds specificity.

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?

No explicit guidance on when to use this tool versus alternatives. The description implies it's for retrieving a specific configuration, but does not mention when to prefer it over list_configs or other get operations.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns revision history and spec, but does not mention permissions, side effects, or whether it is read-only. For a read operation, minimal behavioral insight is given.

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 a single concise sentence that front-loads the essential purpose. It is efficient with no wasted words, though it could benefit from a slight restructure for better scannability.

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?

With no output schema, the description hints at return values ('revision history and spec') but doesn't fully describe the response structure. For a simple get operation, this is minimally adequate, but it lacks completeness compared to more detailed descriptions.

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 0% description coverage, so the description should compensate. However, it does not explain the role of 'organization_uuid' or any constraints beyond format. The description adds no semantic value to the parameters beyond what the schema already shows.

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 action ('Get'), the resource ('a single reusable module'), the identifier method ('by uuid'), and the additional content ('including its revision history and spec'). It effectively distinguishes from sibling tools like 'list_modules' (listing) and 'get_config' (different resource).

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?

No explicit guidance on when to use or not use this tool versus alternatives. The context implies it's for fetching a specific module by UUID, but there is no mention of when to prefer 'get_config' or other siblings. The description is adequate but lacks explicit usage context.

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?

No annotations exist, and the description does not disclose behavioral traits such as read-only nature, result format, pagination, or error handling. The tool's behavior is under-specified.

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 a single concise sentence, but it is too minimal to cover necessary details. It lacks structure or additional context that would normally be expected for a list operation.

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 no output schema, no annotations, and incomplete parameter documentation, the description is insufficient for an agent to fully understand the tool's behavior, return value, or limitations.

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 has 0% description coverage. The description does not explain the single parameter 'organization_uuid' other than its name, leaving its purpose and constraints unclear.

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 verb 'List' and the resource 'AirPipe configurations', with scope 'organization's'. It effectively distinguishes from sibling tools like list_modules and list_organizations.

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?

No guidance is provided on when to use this tool vs alternatives. Missing context for exclusion criteria or prerequisites.

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?

No annotations provided, so description carries full burden. It only mentions listing modules with optional revision history, but does not disclose pagination, sorting, access requirements, or impact of the 'revisions' parameter beyond inclusion.

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 a single sentence with a parenthetical hint, making it concise. However, it omits critical information like the required parameter explanation, which penalizes completeness but not conciseness.

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 no annotations, no output schema, and 0% parameter description coverage, the description is grossly incomplete. It fails to clarify the list's purpose, output structure, or how to use the 'revisions' parameter 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 description references a 'revisions' parameter not present in the input schema, which is misleading. It also fails to explain the only schema parameter 'organization_uuid'. With 0% schema description coverage, the description does not compensate.

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 action (list) and resource (organization's reusable modules), and provides a specific parameter hint (revisions=true). This distinguishes it from siblings like 'list_configs' and 'list_organizations'.

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 gives a usage hint for the 'revisions' parameter but does not explicitly state when to use this tool versus alternatives (e.g., 'get_module' for individual modules). No exclusions or when-not advice.

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. It implies a read operation but does not explicitly state idempotency, authentication requirements, or rate limits. Adequate for a simple listing tool but could be improved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action, no wasted words. Every sentence serves a purpose.

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 zero-parameter tool with no output schema, the description sufficiently explains the purpose and output (organization_uuid). Could mention the output structure more explicitly, but adequate.

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?

There are no parameters (schema coverage 100% trivial), so the baseline is 4. The description adds no parameter details, but none are needed.

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 'List the organizations you belong to and their organization_uuid', specifying the verb (list) and resource (organizations), and distinguishes from sibling tools that deal with configs and modules.

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 explicitly advises 'Call this first to get an organization_uuid for the config tools', establishing it as a prerequisite. It does not exclude alternative uses but provides clear context for when to use it.

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 full burden. It describes the return structure and the intended workflow, but does not explicitly state if the tool is read-only or has side effects. The 'get' verb implies read-only, but it's not confirmed.

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 mostly concise and front-loaded with purpose and return type. The second part about the post-processing pipeline adds value but makes it slightly longer than ideal.

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 the tool's role in the config creation workflow and specifies return fields. However, it omits error cases, parameter details, and does not fully compensate for the lack of output schema. Still fairly complete given no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description does not explain any of the three parameters (request, limit, organization_uuid). It only describes the return structure. The agent lacks guidance on how to fill the required 'request' field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to get config-authoring instructions and RAG examples for a natural-language request, enabling the model to write YAML itself. It distinguishes from generate_config by specifying a different workflow.

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 explicitly advises when to use this tool ('prefer over generate_config whenever you can author YAML yourself') and provides a clear pipeline: validate_config then create_config. This sets clear context versus siblings.

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?

No annotations are provided, so the description carries full burden for disclosing behavior. It only states the action without explaining idempotency, error handling, side effects, or required permissions. Minimal 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?

Description is a single sentence, concise but under-specified. It front-loads the action but lacks structure needed for clarity on toggling behavior.

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 simple toggle tool with only two required parameters, the description is minimally complete but misses details like atomicity of bulk toggle and the nature of 'enable/disable' state.

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 0%. The description mentions 'by config_uuid' but does not elaborate on the meaning of config_uuids (array) or organization_uuid, nor does it clarify array constraints or value formats.

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 verb (enable or disable) and resource (configurations by config_uuid), distinguishing it from sibling tools like create_config, delete_config, or edit_config.

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?

No guidance on when to use toggle_config versus edit_config or update_config. No context about prerequisites or alternatives, leaving the agent to infer usage.

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?

No annotations provided, so description must carry burden. It states 'Undeploy', which clearly indicates a reversal of deploy, but lacks details on permissions, side effects, or reversibility.

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?

Single sentence, no waste. However, it could benefit from slightly more structure (e.g., listing allowed environments). Still efficient.

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 3 required parameters, no output schema, and no annotations, the description is too sparse. Missing parameter details, usage context, and behavioral notes make it incomplete for reliable agent use.

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 has 0% coverage and description does not explain any parameters. Only 'environment' is hinted by mentioning STAGING/PRODUCTION in parentheses, but not explicit. config_uuid and organization_uuid are left undocumented.

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 uses a specific verb ('Undeploy') and resource ('configuration from an environment') and clearly distinguishes from siblings like 'deploy_config_revision' and 'plan_config'.

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?

No guidance on when to use this tool vs alternatives like 'undeploy_module', nor prerequisites (e.g., config must be deployed). The description implies usage but lacks explicit context.

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?

No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits such as destructiveness, whether it removes deployment status, affects dependent resources, or requires special authentication. The description is minimal, only stating the action.

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?

A single, front-loaded sentence with no wasted words. Efficiently communicates the core purpose.

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 lack of annotations and output schema, the description is adequate for a simple operation but leaves gaps like what happens upon success, side effects, and environment validation. It is complete enough for a straightforward tool with many siblings providing 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?

Schema coverage is 0%, so description must compensate. It adds value by specifying that environment takes values STAGING or PRODUCTION, but does not explain organization_uuid or module_uuid. Partially helpful but incomplete.

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?

Description clearly states the action (Undeploy), the resource (reusable module), and the context (from an environment, specifying STAGING or PRODUCTION). It effectively distinguishes from siblings like deploy_module_revision, delete_module, and undeploy_config.

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?

Description implies when to use (to undeploy a module from an environment) but lacks explicit guidance on when not to use it or alternatives. No mention of prerequisites (e.g., module must be deployed) or comparison to similar sibling tools.

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 must fully disclose behavior. It mentions base64 encoding and optional redeploy but does not clarify how redeploy is triggered (parameters deploy_staging/deploy_production), whether updates are destructive, or if config_uuid is required despite not being in required list.

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?

Single sentence is concise but lacks structure. It front-loads core purpose but omits essential details, making it less effective than a more organized alternative.

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 7 parameters and no output schema or annotations, the description is incomplete. It fails to explain parameter roles, side effects, or return values, which is insufficient for correct tool invocation.

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 0%, so the description must compensate. It explains only config_yaml (base64) and config_uuid (identifier) but ignores 5 other parameters (role_uuid, permission, deploy_staging, deploy_production, organization_uuid), leaving their semantics unclear.

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?

Clearly states 'Update an existing AirPipe configuration' and specifies key parameters (config_uuid, config_yaml). However, it does not differentiate from sibling tools like edit_config or deploy_config_revision, which may overlap in functionality.

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?

No explicit guidance on when to use this tool versus alternatives. The description implies updating an existing config but doesn't mention when to use edit_config or deploy tools. Missing prerequisites or conditions.

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 full burden. It discloses that updating adds a new revision (not in-place modification) and that spec_yaml must be base64-encoded. However, it lacks details on permissions, rate limits, error conditions, or what happens to old revisions.

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?

Single sentence efficiently conveys purpose, key detail about new revision, spec_yaml encoding, and optional redeploy. No wasted words.

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 10 parameters, no output schema, and no annotations, the description is too minimal. It does not explain most parameters or return value, making it inadequate for an agent to use 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 schema has 10 parameters with 0% description coverage. The description explains spec_yaml (base64-encoded YAML) and hints at redeployment parameters, but ignores other parameters like handle, role_uuid, permission, description, module_type, and organization_uuid. Insufficient compensation for the schema gap.

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 updates an existing reusable module by module_uuid, adds a new revision, and optionally redeploys. It specifies the verb 'Update' and resource 'module', and distinguishes from siblings like create_module and delete_module.

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 implies usage for updating modules and optionally redeploying, but does not explicitly state when to use this over alternatives like create_module or deploy_module_revision. No prerequisites or exclusions provided.

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?

Discloses that the tool only performs schema checks and does not save data, with no side effects. Describes the return format in detail, including the error message structure, and suggests a retry loop. With no annotations, this fully covers the behavioral aspects.

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?

Three sentences, each serving a distinct purpose: stating what it does, how to call it and what to expect, and how to use the result. No unnecessary words, and critical information 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?

Even without annotations or output schema, the description covers all aspects needed: purpose, input format, output behavior, loop guidance, and alternative tool. For a simple validate tool with one parameter, this is fully sufficient.

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?

Despite 0% schema description coverage, the description explains the sole parameter 'yaml' clearly: it expects the full YAML string. It also specifies the JSON format for sending the parameter, adding valuable context beyond the schema's type and minLength.

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 validates an airpipe YAML config against a schema, with a specific verb and resource. It distinguishes itself from siblings like create_config by noting it does not persist, and from validation tools like plan_config by focusing solely on schema validation.

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 describes the flow: send YAML, receive validation result, loop with fixes until valid. Directly names the sibling create_config as the tool to persist a valid config, providing clear guidance on when to use this tool versus alternatives.

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