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

With no annotations, the description carries the full transparency burden. It discloses the critical gotcha that env vars don't suffice and that explicit invocation is mandatory, and clarifies the different key types for different scopes. While it doesn't describe the exact result of a successful auth (e.g., token storage), it provides substantial behavioral context beyond a simple 'authenticate' statement.

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 compact paragraph of four sentences, but every sentence earns its place: purpose, prerequisite scope, key acquisition link, exception for global endpoints, env var caveat, and key type distinction. No filler or redundancy; it is appropriately structured for a critical auth tool.

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 of an auth tool with multiple key types, no output schema, and no annotations, the description covers all essential aspects: when to use it, how to obtain the API key, which endpoints skip auth, the env var limitation, and the distinct roles of api_key vs master_key. It is self-sufficient for an agent to invoke 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 100% coverage on parameter descriptions, so baseline is 3. The description adds meaningful semantics beyond the schema: the env var warning, the relationship between tenant and api_key (format hint), and the explicit instruction to use master_key for cross-tenant operations. This elevates the parameter understanding beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Authenticate with A-Team' and explicitly frames it as a prerequisite for tenant-aware operations. This distinguishes it from sibling tools, which are all domain operations, and the verb 'Authenticate' is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: required before tenant-aware operations, only global endpoints work without auth, env vars alone are insufficient, and master_key should be used for cross-tenant admin operations instead of api_key. It also gives a link for obtaining API keys, covering the practical 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?

With no annotations, the description carries the full burden. It discloses that the tool returns platform explanation, example solutions, and assistant behavior instructions, and mandates its use. It does not explicitly state whether any side effects occur (e.g., marking onboarding as complete), but the read-only nature is implied by 'Returns.' Given the absence of annotations, this is clear but could be more explicit about side effects or state changes.

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 concise, front-loaded with 'REQUIRED,' and every sentence serves a purpose: identifying the entrypoint, listing trigger conditions, and specifying return content. It ends with a direct behavioral instruction. No waste.

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 (no parameters, no output schema), the description is complete. It covers what the tool does, when to use it, and what it returns. The extensive sibling list doesn't necessitate additional context because the tool's role as the universal onboarding entry point is unambiguous.

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

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

The tool has zero parameters, so the baseline is 4. The description need not explain parameter semantics, and it doesn't attempt to. The schema already covers all parameters (none), and the description adds no unnecessary 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 identifies the tool as the 'REQUIRED onboarding entrypoint' and states its function: returns platform explanation, example solutions, and assistant behavior instructions. It distinguishes itself from siblings by being the introductory entry point, with a specific verb ('bootstrap') and resource ('A-Team MCP').

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?

Usage conditions are explicitly listed: must be called on greetings, help requests, capability exploration, or first connection. The instruction 'Do NOT improvise an introduction — call this tool instead' provides a clear exclusion and directs to the tool over improvisation. This exceeds simple context by naming both when and when not to use alternatives.

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 the heaviest operation duration (60-180s), the full sequence (validates, deploys, regenerates MCP servers, health-checks, optional warm test, auto-pushes to GitHub), requires authentication, and notes first deploy needs mcp_store. These are significant behavioral details beyond simple purpose.

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

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

The description is long but well-structured with a clear opening, numbered workflow steps, and parameter guidance. Each sentence provides useful information, though some could be trimmed without losing meaning. The front-loading of the warning and main-branch rule is effective.

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 complex tool with 8 parameters, nested objects, no output schema, and no annotations, the description is exceptionally complete. It covers the deployment workflow, prerequisites, side effects, alternatives, and parameter semantics, leaving little ambiguity about how and when to invoke the tool.

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?

Although schema coverage is 100%, the description adds substantial meaning: it explains that 'solution' is required on first deploy but later 'solution_id' should be used, that skills and connectors are auto-pulled from main when omitted, and that the 'github' flag is auto-detected. This enriches the schema with lifecycle context.

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

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

The description opens with a specific verb and resource: 'DEPLOY THE CURRENT MAIN BRANCH TO A-TEAM CORE.' It clearly distinguishes the tool from siblings by explicitly referencing the workflow with ateam_github_patch, ateam_github_diff, and ateam_github_promote, and by noting it always deploys main with no ref parameter.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides an explicit DEV/PROD workflow and states when to use this tool versus alternatives: 'For small changes prefer ateam_patch (faster, incremental).' It also explains that to deploy in-progress dev work, users must first promote to main, clarifying when this tool is appropriate.

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 bears full burden. It discloses key behaviors: auto-routing to the right skill, multi-turn context maintenance via actor_id, and the wait/timeout mechanism. However, it does not cover potential side effects, auth requirements, or error scenarios.

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 three sentences, efficiently front-loading the core purpose, then key feature (auto-route), and finally multi-turn detail. Every sentence adds value without redundancy.

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 parameter count and schema coverage, the description adequately explains usage patterns. It lacks details on return value format, which might be important for an agent, but no output schema exists to compensate. Still, it covers essential behavioral aspects.

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 100% schema coverage, baseline is 3. The description adds value beyond the schema by explaining actor_id for conversation continuation, wait default, and timeout defaults/max detail, which are not fully evident from the schema descriptions alone.

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 sends a message to a deployed solution and gets a result. It distinguishes from siblings by highlighting auto-routing without skill_id, making it unique among tools like ateam_test_skill.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use: for sending messages to deployed solutions and multi-turn conversations. It explains how to continue a conversation via actor_id but does not explicitly state when not to use it or list alternatives, though the sibling list implies differentiation.

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

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: eliminating boilerplate, including optional stubs, and uploading files to Core after scaffolding. However, it does not mention whether existing files are overwritten, what happens on failure, or any authentication/permission requirements, leaving some uncertainty.

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 front-loaded with the core purpose and uses four sentences to convey necessary details: boilerplate reduction, fill-in step, ui_capable option, and upload path. It is slightly dense with parentheticals but remains concise and each sentence adds value.

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 what files are created, the optional ui_capable behavior, the relationship to plugin creation, and the upload mechanism. With no output schema and no annotations, it provides a reasonable level of completeness for a scaffolding tool, though it could be improved by stating prerequisites or error 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 100%, so the schema already fully documents all four parameters. The description adds context around ui_capable and connector_id but largely repeats what the schema says, so it provides baseline rather than enhanced semantic value.

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

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

The description opens with a specific verb and resource: 'Scaffold a new MCP connector with server.js + package.json + README.' It clearly distinguishes from siblings by mentioning plugin files are handled separately (ateam_create_plugin) and that uploads follow the same path as ateam_upload_connector.

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 this is for creating a new connector from scratch, stating you then 'fill in the tool implementations.' It references an alternative for plugin files (ateam_create_plugin) and clarifies the upload relationship with ateam_upload_connector, though it doesn't explicitly list when-not-to-use scenarios.

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 explains the tool scaffolds plugins and auto-discovers at next deploy, but does not disclose potential side effects, authentication needs, or rate limits. It adds some behavioral context but could be more comprehensive.

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 concise with four sentences, front-loaded with purpose. It avoids fluff, though the reference to 'Phase 5 of the strip' may be unclear to new users.

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 and no annotations, the description covers the essential aspects: what it does, parameter usage, and post-action behavior (auto-discovery). It is adequate for a scaffolding tool, though return values are not mentioned.

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?

Although schema coverage is 100%, the description adds value by explaining the kind enum values, giving an example for connector_id, and noting plugin_name becomes the directory name. This goes beyond the schema definitions.

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 scaffolds a UI plugin inside an existing connector, specifying types (iframe, rn, adaptive) and the benefit of eliminating boilerplate. It distinguishes from siblings like ateam_create_connector by focusing on plugin creation.

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?

It provides guidance on when to use each kind value (iframe for web, rn for mobile, adaptive for both) and implies the prerequisite of an existing connector. However, it does not explicitly mention when not to use this tool or suggest alternative 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?

No annotations provided, so description carries full burden. It details the effects: stops connector, deletes from A-Team Core, removes references in solution definition and skill definitions, cleans up mcp-store files. This gives good insight into the operation's impact.

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 with bullet-like list of actions, no fluff. Efficiently conveys all necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a delete operation with no output schema, the description fully explains what happens. Could mention if operation is idempotent or error conditions, but overall 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?

Schema coverage is 100%, so baseline is 3. Description adds examples but no extra semantics beyond what the schema already provides.

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

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

Clearly states 'Remove a connector from a deployed solution' with specific actions (stops, deletes, removes references, cleans up). Distinct from sibling tools like ateam_create_connector and ateam_delete_skill.

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?

Implied usage for removing connectors, but no explicit when-to-use or when-not-to-use compared to alternatives. Lacks prerequisites or exclusion criteria.

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

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

With no annotations, the description fully covers behavioral effects: kills MCP process, unregisters from skill registry, deletes from Mongo, removes from solution arrays, deletes files from Builder FS. This fully informs the agent of the destructive nature and 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.

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

The description is three sentences: clear purpose, detailed effects, and closing usage guidance. No redundant words, and every sentence adds value.

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 number of sibling tools and the complexity of the operation, the description is complete. It explains what, how, and when to use, without needing an output schema for a delete operation.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds no extra meaning beyond what the schema provides, meeting the baseline for high 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 'Delete a single skill from a deployed solution,' specifying the verb and resource. It distinguishes from sibling delete tools like ateam_delete_connector and ateam_delete_solution by clarifying it targets a single skill within a solution.

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 implicitly provides usage context with 'Use this to drop a skill without tearing down the whole solution,' indicating when this tool is appropriate. However, it does not explicitly mention alternatives or cases where it should not be used, relative to other 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?

Discloses destructive behavior: removes the solution from both Skill Builder and A-Team Core. With no annotations provided, this description adequately informs about the irreversible nature and scope of deletion.

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 concise sentences with no waste. Front-loaded with purpose, then adds caution and use case. Every sentence earns its place.

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 delete tool, description covers purpose, usage guidance, and behavioral effects. Lacks mention of return value, but no output schema exists. Adequate for the tool's complexity.

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?

Single parameter 'solution_id' with clear schema description. High schema coverage (100%) means description adds no extra meaning beyond what's already in the schema. Baseline score of 3 is appropriate.

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 it deletes a deployed solution and all its skills from A-Team, specifying the resource and action. It distinguishes from sibling tools like ateam_delete_skill by noting it removes the entire solution.

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 advises caution and states it is useful for cleaning up test solutions or starting fresh. Provides clear context for when to use, though it does not explicitly name alternative 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?

Without annotations, the description carries the burden. It states a read operation ('Read') and describes the return (all files stored in mcp_store). While it doesn't detail error handling or permissions, the behavior is straightforward and non-destructive, so transparency is good but not exhaustive.

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: first sets purpose and return, second gives usage guidance. Both sentences are valuable and concise, with no extraneous information. It is front-loaded with the core action.

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 read tool with two parameters and no output schema, the description covers the purpose, return content, and usage context. It could mention that it returns file contents or list of file names, but it gives examples ('server.js, package.json, etc.'). It is fairly complete for the tool's complexity.

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

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

The input schema already describes both parameters (solution_id and connector_id) with clear examples. The description does not add any additional semantics or usage details for the parameters beyond what the schema provides. With 100% schema coverage, baseline is 3.

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 ('Read') and the resource ('source code files of a deployed MCP connector'). It distinguishes from sibling tools by specifying that it reads current code before patching or rewriting, which differentiates it from write-oriented siblings like ateeam_patch and ateeam_create_connector.

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: 'Use this BEFORE patching or rewriting a connector — always read the current code first so you can make surgical fixes instead of blind full rewrites.' This provides clear context and an exclusion (not for writing or modifying).

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 correctly indicates a read-only retrieval operation ('get'), but provides no details about side effects, authentication needs, or return behavior. This is adequate for a simple fetch but lacks extra context.

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

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

Two short sentences, front-loaded with the action. The second sentence adds usage hint but is not strictly necessary. Still efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description should disclose the return format (e.g., file paths, content). It does not, leaving uncertainty for the agent about how to use retrieved 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?

Schema coverage is 100% with enum descriptions for each type, so the baseline is 3. The description does not add any additional meaning about the parameter beyond what the schema already provides.

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

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

The description states 'Get complete working examples that pass validation' with a clear verb and resource. Combined with the enum parameter specifying example types, the tool's purpose is unambiguous and distinct from all sibling tools.

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 phrase 'Study these before building your own' implies a learning usage, but there is no explicit guidance on when to use this tool versus alternatives or when not to use it. No exclusions or alternatives are mentioned.

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 must fully disclose behavioral traits. It indicates a read operation but does not mention authentication needs, side effects, idempotency, or performance characteristics.

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 concise (one sentence) and front-loaded with the action, effectively summarizing the tool's purpose without extraneous 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 no output schema and no annotations, the description covers the overall purpose and view options but lacks details on output format, error conditions, or permission requirements.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; it merely restates the purpose.

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 a specific verb ('Read') and resource ('solution state — definition, skills, health, status, or export'), distinguishing it from sibling tools that perform writes or list all solutions.

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?

It says 'Use this to inspect deployed solutions,' providing positive context, but lacks explicit guidance on when not to use it or alternatives for listing or modifying solutions.

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. Discloses that using 'section' gives a much smaller output, but lacks details on side effects, auth requirements, or data freshness. Adequate but not rich.

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?

Concise, front-loaded, and no fluff. Every sentence earns its place, efficiently conveying purpose and usage.

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 parameters with enums and no output schema, description covers when, why, and how to use filters. Could mention output size but not critical. Very complete for a read-only spec retrieval tool.

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

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

Schema coverage is 100% and description adds context beyond schema, e.g., 'Start here after bootstrap' and explains how to use parameters to filter results. Adds marginal value over schema.

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

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

Clearly states it gets the A-Team specification with specific contents (schemas, rules, guides). Distinguishes from sibling tools by mentioning alternatives like 'section' and 'search' for subset retrieval.

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 tells when to use ('Start here after bootstrap') and provides clear guidance on alternatives: using 'section' for a smaller subset and 'search' for targeted retrieval.

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?

Annotations are absent, so the description carries the full burden. It discloses the return content ('phases, what to ask, what to build, exit criteria, and tips') but does not explicitly state the read-only nature or any prerequisites. The verb 'Get' implies non-mutation, but a direct statement about side effects is missing, so transparency is moderate.

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 three concise sentences that front-load the purpose, then add a usage cue, and finish with return content. No filler words; every clause contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with no parameters or output schema. The description covers the essential return information ('phases, what to ask, what to build, exit criteria, and tips for each stage'), which is sufficient for an agent to understand what it will get. It could specify the exact format, but for a conversational guide this is complete enough.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. The description does not need to add parameter detail. The baseline for zero-parameter tools is 4, and the description correctly omits any parameter information.

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 names the resource ('builder workflows') and the action ('Get'), and explains what they are ('step-by-step state machines for building skills and solutions'), distinguishing this tool from sibling get tools like get_spec or get_examples by focusing on the build workflow guide.

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 states 'Use this to guide users through the entire build process conversationally,' providing clear context for when to invoke it. It does not explicitly name alternatives or exclusions, but the instruction is sufficient for selection.

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. Description fully discloses behavior: compares branches, shows commits/files, returns ahead_by. No destructive implications.

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?

Concise 4 sentences with bullet points. Front-loaded purpose, then usage. 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?

Adequately describes input, behavior, and output (ahead_by). No output schema but description covers key return info.

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 100% but description adds value by explaining defaults and ability to override for arbitrary comparisons.

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 specific verb 'compares dev vs main' and links to promote tool. Clearly distinguishes from sibling tools like ateam_github_promote and ateam_github_log.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit bullet points on when to use (review before promote, check if dev is ahead, arbitrary comparisons). Lacks explicit when-not but context is clear.

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 present, so the description carries the full burden. The verb 'List' implies a read-only operation, but the description does not explicitly state 'does not modify' or disclose any other behavioral traits. It does add useful context by specifying the safe-* tag pattern and output fields, but stops short of full transparency.

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

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

The description is only two sentences, front-loaded with the primary action, and every sentence provides value. It is concise without sacrificing needed 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?

For a simple list tool with one parameter and no output schema, the description covers the purpose, the exact items listed (safe-* tags with fields), and when to use it. It is complete for the tool's complexity.

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

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

The input schema already fully describes the single parameter (`solution_id` with type and description). The tool description does not add any additional semantic detail about the parameter beyond what the schema provides. With 100% schema coverage, the baseline of 3 is appropriate.

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 ('List') and resource ('available checkpoints') for a solution, and clarifies they are 'safe-* tags'. This clearly distinguishes it from siblings like rollback or status tools, and even mentions the key output fields.

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 states when to use it: 'Use before rollback to see available safe points.' This provides clear context for invocation. It does not mention alternatives or when not to use it, so it doesn't earn a 5.

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 transparency burden. It discloses that this is a read operation ('View', 'reads'), states the default branch is production, and lists the return fields. It does not mention pagination limits or auth, but the read-only nature and default behavior are well conveyed.

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 compact sentences front-load the purpose and immediately give the most important usage tip. Every word earns its place; no filler, fluff, or repetition of schema 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?

For a simple read-only tool with three parameters and no output schema, the description covers purpose, output contents, and branch semantics. It could mention auth requirements or error behavior, but given the tool's simplicity and the schema's completeness, this is adequate and near-complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the real-world meaning of the `ref` parameter (prod vs dev) and confirming the default branch. The `limit` parameter is present in the schema with a default, and while not detailed in prose, the schema already handles it.

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

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

The description opens with a specific verb and resource: 'View commit history for a solution's GitHub repo.' It clearly distinguishes this from sibling github_* tools like diff, read, or status by stating the exact output (commits with messages, SHAs, timestamps, links).

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?

It gives clear context on when to use the default 'main' branch (prod) and when to pass 'ref: 'dev'' for in-progress work. It does not explicitly name alternative tools or exclusion cases, but the branch guidance is practical and sufficient for a tool whose sibling alternatives are obvious from names.

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?

Without annotations, the description carries the full burden. It explains the two modes, default branch, and the need for exact text in search. It could mention required permissions or what a commit returns, but overall it is transparent about the tool's behavior.

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 concise yet comprehensive, using bullet points for clarity. Every sentence adds value: modes, best practices, branch safety, and alternatives. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers modes, branch safety, prerequisites, and sibling differentiation. Missing output details (e.g., commit info), but there is no output schema. For a mutation tool, a note on what is returned would be helpful, but the description is still quite complete.

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

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

The input schema already describes each parameter (100% coverage), so baseline is 3. The description adds value by explaining the two modes and when to use content vs search+replace, providing context beyond the schema's individual descriptions.

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 a file in a GitHub repo and commits, with two modes (full file and search/replace). It distinguishes itself from sibling tools like ateam_github_read (which reads) and ateam_github_promote (which promotes branches).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: use search/replace for large files >5KB, always read the file first with ateam_github_read, defaults to dev branch, use ateam_github_promote to ship to main, and pass ref='main' only for emergency hotfixes. This helps the agent choose the correct mode and avoid mistakes.

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 the key behavioral traits: merges dev→main, auto-tags HEAD, returns 409 on conflict, supports dry_run and skip_tag. It could mention idempotency or success response format, but the existing detail is strong.

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 tightly written: two sentences convey purpose and workflow, then lists steps and options. No extraneous words; every sentence adds value. Front-loaded with key action.

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, the description covers error handling (409 on conflict), optional behaviors (dry_run, skip_tag), and the workflow sequence. It lacks an explicit statement of what a successful invocation returns (e.g., confirmation or tag name), but the context is largely complete for an experienced developer.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema: labels are 'human-readable for the auto-tag', dry_run 'show the diff without merging', skip_tag 'merge without creating an auto-tag'. It effectively explains the why and how of each parameter.

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 states explicitly: 'SHIP DEV TO PROD. Merges the dev branch into main and auto-tags...' This clearly identifies the action (merge) and resource (dev to main), and distinguishes it from sibling tools like ateam_github_patch and ateam_github_rollback via the 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?

Guidelines are explicit: 'Use after testing your dev work, when you're ready to deploy changes to production.' It also provides when not to use: on merge conflict, resolve manually. Additionally, it offers the alternative dry_run mode and positions the tool in a workflow sequence (patch → promote → build_and_run).

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 carry the full burden. It discloses what files are read and that data feeds into the deploy pipeline, which is useful. However, it doesn't mention potential side effects (e.g., overwriting existing deployment), required permissions, or reversibility—leaving gaps in 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?

Two sentences, front-loaded with the primary purpose, followed by a succinct use-case statement. No filler or redundant content—every word earns its place.

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 one-parameter tool with no output schema, the description adequately covers its function, inputs, and typical usage. It could mention prerequisites like the need for a .ateam/export.json file, but overall it is sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100% and the only parameter (solution_id) is clearly described as 'The solution ID to pull and deploy from GitHub.' The tool description adds no new parameter information beyond what the schema already states, so baseline 3 applies.

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

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

The description opens with a clear, specific action: 'Deploy a solution FROM its GitHub repo.' It further clarifies the mechanism (reads .ateam/export.json + connector source) and distinguishes this tool from siblings like ateam_github_push and ateam_redeploy by explaining its role as pulling from GitHub to 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 provides explicit use cases: 'Use this to restore a previous version or deploy from GitHub as the source of truth.' This gives clear context for when to choose this tool, though it doesn't name alternative tools or state 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, the description carries the full burden. It discloses important behaviors: auto-creates the repo on first use and commits the full bundle atomically. However, it does not mention authentication requirements, remote conflict handling, or whether the push is a force push, leaving some gaps.

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 three sentences, front-loaded with the core action. Each sentence provides distinct value: the primary function, key behaviors, and usage guidance. No redundant or filler content.

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 exists and annotations are absent, but the description covers inputs (via schema), side effects, and usage timing. It omits response/error details, but for a straightforward push operation, it is nearly complete.

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

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

Schema coverage is 100% with both parameters described. The description adds no extra parameter semantics beyond the schema, which already documents solution_id and the optional commit message. Baseline 3 is appropriate.

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 ('Push') and resource ('current deployed solution to GitHub'), and adds unique context about auto-creating the repo and committing the full bundle atomically. This distinguishes it from sibling tools like ateam_github_pull or ateam_github_write.

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 tells when to use the tool: after ateam_build_and_run to version the solution, or anytime to snapshot the current state. It provides clear context but does not explicitly mention when not to use it or name alternatives beyond the referenced build tool.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool reads from a GitHub repo, returns file content, defaults to 'main' branch, and supports a 'ref' parameter for development branches. It does not describe non-obvious behaviors like permissions or rate limits, but for a read operation the transparency 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.

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

Three sentences, no wasted words. Front-loads the core purpose, then provides usage details and examples. 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 read tool with three well-documented parameters and no output schema, the description is complete. It covers what the tool reads, how to specify the branch, and file path examples. No gaps identified.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description adds value by explaining the default and usage of 'ref' and providing concrete path examples, enhancing understanding beyond the schema.

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

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

The description states explicitly that it reads any file from a solution's GitHub repo and returns content, with concrete examples (connector source code, skill definitions). This clearly distinguishes it from sibling tools like ateam_github_write or ateam_github_diff.

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 clear context on when to use default branch (main/prod) vs the 'dev' ref for in-progress work. While it doesn't explicitly exclude alternatives, the guidance on ref usage is helpful. Missing comparison to other read tools like ateam_github_log but still informative.

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 responsibility for behavioral disclosure. It explicitly states the operation is ADDITIVE, does NOT destroy history, creates a new commit whose tree matches the target, preserves history, and allows rolling back the rollback. This is exceptionally transparent about side effects and safety profile.

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 compact yet structured: a one-line summary, a behavioral clarification, and a numbered workflow. Every sentence is purposeful, with no redundancy. The use of formatting (capitals, bullets) enhances readability without bloating length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description covers purpose, behavior, workflow, and parameter selection. It explains the safety mechanism and tells the user how to proceed before and after. The only minor omission is explicit mention of remote/push behavior, but 'Roll prod' implies remote, and the workflow covers deployment next steps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by placing the target parameter in the workflow context, explaining that safe-* tags should be found via list_versions. This enriches understanding of how to populate the parameter beyond the schema's static description.

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

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

The description clearly states the tool's function: 'Roll prod (`main` branch) back to a previous state.' It uses a specific verb (roll back), identifies the resource (prod main branch), and explicitly differentiates from sibling tools like patch/promote/write by describing the additive commit behavior. This is a precise, non-tautological purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear three-step workflow: find a safe-* tag with ateam_github_list_versions, invoke rollback, then deploy with ateam_build_and_run. This gives strong guidance on when to use the tool. However, it does not explicitly state when NOT to use it or compare to alternative revert strategies (e.g., ateam_github_patch), so a minor gap remains.

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 responsibility. The 'check' verb implies read-only, and it specifies the data returned (URL, latest commit), but it does not explicitly confirm no side effects or address failure modes.

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, no fluff, front-loaded with the action. Every word earns its place.

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 status tool, it includes purpose, output details, and use case. It lacks error behavior details, but overall adequate for the tool's complexity.

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 covers solution_id at 100% with a basic description; the description adds no new detail about parameter format or constraints. Baseline 3 applies.

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

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

Description uses specific verb 'check' and clearly identifies the resource (solution's GitHub repo) and outputs (URL, latest commit). This distinguishes it from sibling tools like diff, push, or log.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit use case: 'verify GitHub integration is working for a solution.' However, it does not mention when not to use or list alternatives, so it lacks explicit exclusions.

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

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

With no annotations, the description carries the burden. It discloses key behavior: writes to the GitHub repo, defaults to the dev branch, supports overwriting ('replace existing ones'), and is limited to one file per call. It also implies the write does not deploy, since separate promote and build steps are needed. This goes beyond a simple mutation statement.

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 dense sentences: the first establishes purpose and distinctiveness, the second gives the workflow and default branch. No wasted words, all information is actionable. The structure front-loads the most critical information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description provides a surprisingly complete picture for a write tool with no output schema: it explains the exact sequence of related tool calls (write→promote→build), the default branch, and the one-file limit. It could mention error behavior or prerequisites, but for its purpose it is nearly complete.

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

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

Schema description coverage is 100%, so each parameter is documented. The description adds the usage-level constraint of 'one file per call' but doesn't clarify parameter formats or interactions beyond what the schema already provides. Baseline 3 is appropriate as the schema does the heavy lifting.

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 'Write a file to the solution's GitHub repo' and specifies the use case: 'create new connector files or replace existing ones — one file per call.' It also distinguishes itself from sibling tools by calling itself the 'PRIMARY way to write connector code after first deploy' and references the deploy 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 provides explicit when-to-use guidance ('Use this to create new connector files or replace existing ones') and a clear sequence: 'Write each file individually... then call ateam_github_promote()... then ateam_build_and_run() to deploy.' It also mentions the one-file-per-call constraint, giving clear operational 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?

With no annotations provided, the description carries the full burden of behavior disclosure. It states a list operation but does not mention readability, return format, or any side effects or limits. This is minimal transparency for a simple tool.

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 of eight words with no filler. It is appropriately sized and 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?

The description covers the basic purpose but lacks detail on the return value structure (e.g., fields or format) and any limitations. Since there is no output schema, the description should explain what the list contains, which is absent. Given the simplicity, it is slightly incomplete.

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

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

The tool accepts zero parameters, and the schema coverage is 100%. Per the rubric, 0 parameters earns a baseline of 4, and the description adds no parameter-specific information, which is acceptable.

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 the specific verb 'List' with the resource 'solutions deployed in the Skill Builder', clearly distinguishing the action of enumerating all solutions from sibling tools like ateam_get_solution or ateam_show_solution_minimal.

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 retrieving an inventory of solutions but does not explicitly state when to use this tool over alternatives such as get_solution or show_solution_minimal, nor does it mention any 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?

The description discloses behavioral traits such as automatic redeployment, optional re-testing, and the ability to create default scaffolds for new skills. No annotations are present, so the description carries the full burden, and it meets the need by covering mutation side effects and supported operations.

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

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

The description is well-structured with sections (supported operations, examples) and is front-loaded with the core purpose. While lengthy due to exhaustive examples, every part earns its place. It is concise given the complexity of the tool.

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 and lack of output schema, the description covers usage, parameters, special patterns, and behavioral notes (redeploy, test, creation). It leaves no obvious gaps for an agent to understand how to invoke the tool correctly.

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

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

With 100% schema coverage, the baseline is 3, but the description adds significant value by explaining dot notation, array operations (_push/_delete/_update), special fields like _force_redeploy, and providing detailed examples. This greatly enhances understanding beyond the raw schema.

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

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

The description clearly states the tool's purpose: 'Surgically update ANY field in a skill or solution definition, redeploy, and optionally re-test — all in one step.' This provides a specific verb, resource, and scope, distinguishing it from sibling tools like ateam_get_solution (read-only) or ateam_delete_skill (destructive).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use target='skill' vs target='solution', and includes numerous examples covering common update patterns. It also clarifies that the tool can create new skills if they don't exist. However, it does not explicitly state when not to use this tool (e.g., for simple reads).

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 weight. It discloses that this is a 'HEAVY OPERATION' that regenerates MCP servers, pushes to Core, restarts connectors, verifies tool discovery, and takes 30-120 seconds. This gives the agent a strong sense of side effects and cost.

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 front-loaded with the core purpose, then adds a clear warning about the operation's weight and duration, then provides usage guidance. Every sentence earns its place without 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?

For a heavy operation with no output schema, the description covers what happens (regenerates, pushes, restarts, verifies), how long it takes, when to use it, and when to prefer an alternative. This is fully complete for the agent to decide and invoke appropriately.

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

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

Schema coverage is 100%, so the schema already documents both parameters fully. The description does not add extra parameter-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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: 'Re-deploy skills WITHOUT changing any definitions.' This is a specific verb (re-deploy) and resource (skills), and it distinguishes itself from siblings by explicitly contrasting with ateam_patch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage guidance: 'Use after connector restarts, Core hiccups, or stale state. For incremental changes, prefer ateam_patch (which updates + redeploys in one step).' This clearly tells when to use and when to use an alternative.

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 discloses behavioral traits such as the limited content scope and the substantial size reduction (~10x smaller), which informs performance expectations. It does not explicitly state that it is read-only, but the verb 'Show' and the term 'view' strongly imply a non-mutating operation. This is useful but not exhaustive.

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 and front-loaded with the primary action and scope. It then provides a comparison and usage condition. Every sentence contributes value, with no redundancy or unnecessary filler.

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 fully covers what the tool returns (specific authoring components), compares it to an alternative, and explains when to use it. With only two required ID parameters and no output schema, no additional context is needed for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so both parameters (solution_id and skill_id) are already documented. The description adds no extra semantic detail about the parameters, only mentioning them indirectly through 'skill' and 'solution'. Since the baseline for full schema coverage is 3, this is appropriate.

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

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

The description clearly states the tool's function: 'Show the minimal authoring view of a skill' with an explicit enumeration of included components (persona, connectors, handoff_when, style, policy guardrails). It also distinguishes itself from the sibling 'ateam_get_solution' by noting it is '~10× smaller', making the purpose specific and differentiated.

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 explicit guidance: 'Use this when you only need the irreducible author content (Phase 9 of the strip).' It also contrasts with ateam_get_solution(view:'skills') by size, effectively telling the agent when to choose this tool over that alternative.

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 transparently discloses exactly which fields are included and which are omitted (deployed metadata, handoffs, grants, ui_plugins, validation results), setting expectations for output. Minor gap: no mention of read-only nature or error behavior, but 'Show' and 'inspection' imply non-mutating.

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 compact and information-dense, front-loading purpose and field list. The cryptic reference to 'Phase 9 of the strip' adds little for an outside agent and could be removed.

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 single parameter, full schema coverage, and no output schema, the description does a good job explaining what the tool returns and what it omits. It lacks explicit return formatting or error cases, but for a minimal-inspection tool this is 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?

The schema already provides 100% coverage for the single parameter (solution_id with description 'The solution ID'). The description adds no additional parameter-level details, so the baseline score of 3 is appropriate.

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 ('Show') with a specific resource ('minimal authoring view of a solution') and enumerates exact fields included, clearly distinguishing it from the fuller solution tools like ateam_get_solution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this for fast inspection without the verbose fields,' clearly indicating the intended scenario. It also lists what is skipped, providing an implicit exclusion; however, it does not name alternative sibling tools explicitly.

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 must carry the burden of behavioral disclosure. It adds valuable context beyond the name by stating the authentication requirement and the return format ('summary table'). The verb 'Show' implies a read-only operation, but the description does not explicitly confirm no side effects or mention rate limits or failure modes. Still, it provides useful behavioral context for a simple status tool.

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 exceptionally concise, consisting of two sentences that front-load the primary purpose and then add the authentication and return-format details. Every clause adds value with no redundancy or filler.

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 (no parameters, no output schema), the description covers the essential elements: what it does, the required authentication, and the output nature. It could note potential limitations (e.g., requires admin privileges, performance across many tenants), but for a status-list tool, the description is nearly complete.

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

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

The tool has zero parameters, so the schema is trivially complete and the description has no burden to explain parameters. The description instead clarifies what the result will contain (summary table of every tenant's solutions with GitHub sync state), which is helpful even without parameters. This aligns with the baseline for zero-parameter tools.

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

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

The description clearly states the tool's function with a specific verb ('Show') and resource ('GitHub sync status for ALL tenants and solutions'). It also highlights its scope ('ALL tenants and solutions in one call'), which distinguishes it from sibling tools like ateam_github_status that likely target individual tenants or repositories.

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 a prerequisite ('Requires master key authentication'), which is a usage condition. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or mention that for a single tenant/solution, another tool might be more appropriate. The usage context is implied by the 'ALL' scope but not elaborated.

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 discloses the operation sequence, authentication requirement, and return format (summary table). It does not mention partial mode behavior or failure handling, but for a sync tool it is reasonably transparent.

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 core action, and no extraneous detail. Every clause earns its place, covering action, scope, authentication, and output efficiently.

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 provides the overall flow, authentication, and output, which is sufficient for a bulk sync tool with two boolean parameters fully described in the schema. It could mention partial modes or error behavior, but the schema fills the parameter gap, making this fairly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema, and notably does not mention the pull_only/push_only options, which could be misleading if one assumes a full sync only.

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 'Sync', the resource 'ALL tenants', and the exact flow (push Builder FS → GitHub, then pull GitHub → Core MongoDB). It also mentions the output (summary table), and the 'ALL tenants' scope distinguishes it from sibling push/pull tools.

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?

'Sync ALL tenants' clearly implies a bulk sync scenario, and the two-step sequence is explicit. It also mentions the master key requirement. However, it does not explicitly say when not to use it or mention alternatives like individual push/pull 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?

No annotations are provided, so the description must cover behavioral traits. It states abort happens at the next iteration boundary, giving some detail on execution. However, it does not disclose side effects (e.g., state of the test), reversibility, or safety considerations for repeated calls. For an 'advanced' action, more transparency is needed.

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 extremely concise: one sentence plus a parenthetical. Every word earns its place, front-loading the core action. No redundancy or unnecessary 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 the tool's simplicity (3 required params, no output schema) and lack of annotations, the description is adequate but could be more complete. It omits error conditions (e.g., aborting a non-existent or finished job) and consequences, which would help the agent use it safely.

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

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

Schema coverage is 100% with minimal descriptions for each parameter (e.g., 'The solution ID'). The tool description adds no additional meaning beyond the schema. Since the parameters are straightforward and the schema already conveys their purpose, 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.

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

The description clearly states the action ('Abort a running skill test') and the resource. It adds detail about when the abort occurs ('at the next iteration boundary') and marks it as advanced. This distinguishes it from siblings like ateam_test_skill (run) and ateam_test_status (status).

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 the tool is for stopping a running test but does not explicitly state when to use it versus alternatives or when not to use it. It lacks prerequisites (e.g., need a job ID from a running test) or exclusion criteria. The '(Advanced.)' tag hints at caution but provides no specific guidance.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It explains that the tool calls the connector tool and returns the result, and notes the connector must be running. However, it does not mention potential side effects of calling live connector tools, authentication requirements, or error behavior, which could be important for a testing utility that may execute real operations.

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 long and front-loaded with the primary action. Every sentence earns its place: the first states what it does, the second explains when to use it and the required precondition. No filler or redundancy.

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 is complete for a testing tool of moderate complexity. It covers the purpose, usage context, examples, and a key prerequisite. The absence of an output schema is mitigated by the phrase 'get the result,' and the schema already documents all parameters. It could be richer by mentioning response format, but current coverage is sufficient for an agent to invoke it correctly.

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

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

The input schema covers all four parameters with descriptions, including examples for 'tool' and 'connector_id.' The description adds useful context by giving example tool names and noting that 'args' are optional. With 100% schema coverage, the baseline of 3 is appropriate; the description does not significantly increase parameter understanding beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Call a tool on a running connector and get the result.' It clearly identifies the tool's function and distinguishes it from sibling testing tools (e.g., ateam_test_skill, ateam_test_pipeline) by focusing on connector tools and providing concrete examples like 'triggers.list' and 'entities.list'.

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 says 'Use this to test individual connector tools... without deploying to a client,' providing clear when-to-use guidance. It also gives a prerequisite: 'The connector must be connected and running.' It does not explicitly list exclusions or alternatives, but the context is clear enough.

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 discloses rate limiting (10 calls/min), audit trail, tenant scoping via Core's Mongo isolation, [TEST] prefix to prevent phishing, and the security rationale for ignoring reply_handler. This far exceeds baseline and fully compensates for missing annotations.

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?

Despite length, the description is organized into clear sections (purpose, usage, auth, safety) and every sentence delivers critical information. No filler or redundancy; the structure makes it easy to scan.

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 an output schema, the description specifies the delivery-result verification outcome and covers auth, rate limits, tenant isolation, and audit. For a high-stakes testing tool, this is fully complete.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. The description supplements by explaining tenant scoping, [TEST] prefix, and rejection of cross-tenant actors, but most parameter meaning is already captured in the schema. Baseline 3 is appropriate.

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

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

The description opens with a clear verb+resource: 'Fire a REAL notification at an existing actor in a deployed solution' and explicitly contrasts with ateam_test_skill and ateam_conversation, distinguishing its system-initiated real-channel behavior. This fully differentiates it from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit 'Use for' bullets and an explicit alternative: 'For routing/engagement tests, use ateam_test_skill.' Also states when not to use (reply_handler unsupported). Clear context with exclusions and alternatives.

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 burden. It discloses key behavioral traits: it runs a dry-run (doesn't execute tools), what it returns (intent classification, first planned action, timing), and a debugging use case. It could add more about error conditions, but the core behavior is transparent.

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 and scope, followed by outputs and use case. No filler—every word contributes.

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 3-parameter, no-annotation, no-output-schema tool, the description covers purpose, non-execution, return values, and the debugging scenario. It doesn't explain edge cases or what 'timing' refers to, but the essential context is present.

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 100% coverage with self-descriptive parameters (message, skill_id, solution_id). The description adds no extra parameter detail, so the baseline of 3 is appropriate.

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 'Test' with a clear resource 'decision pipeline (intent detection → planning)' and explicitly notes it does NOT execute tools. This distinguishes it from siblings like ateam_test_skill or ateam_test_connector.

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?

It explicitly states 'Use this to debug why a skill classifies intent incorrectly or plans the wrong action' and the 'WITHOUT executing tools' provides a when-not. However, it does not name an alternative tool for execution testing, so it stops short of a full comparison.

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. Discloses default wait up to 60s and async option with job_id. Lacks details on timeout, errors, or idempotency, but core behavior is covered.

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

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

Two sentences, front-loaded with purpose, no wasted words. Highly concise and well-structured.

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, so description should explain return format. Mentions 'full execution result' and 'job_id', but lacks detail on what the full result contains. Could be more complete for agent usage.

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

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

Schema coverage is 100%, baseline is 3. Description adds value for the `wait` parameter by explaining sync/async behavior, but does not add semantic info for other parameters beyond what schema already provides.

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

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

Clearly states the action ('send a test message'), the resource ('deployed skill'), and the output ('full execution result'). Distinguishes from siblings like ateam_test_status (polling) and ateam_test_abort.

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?

Explains when to use sync vs async mode and directs to ateam_test_status for polling. Does not explicitly mention when not to use, but context is clear.

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 discloses that this is a polling operation, returns specific data, and is marked as 'Advanced'. It doesn't detail error handling or rate limits, but for a polling tool this 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.

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

Two efficient sentences: first defines purpose and output, second gives usage guidance. 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?

Despite no output schema, description enumerates return fields well. Parameters are fully covered by schema. Usage guidance is included. Complete for a simple polling tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds no extra parameter semantics beyond what schema already provides, so baseline score.

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 it polls progress of an async skill test, listing return values (iteration count, steps, status, result). It distinguishes from sibling ateam_test_skill by positioning itself as the async polling counterpart.

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 tells when to use (polling async test) and when not (use ateam_test_skill with wait=true for synchronous), providing a direct alternative.

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 of behavioral disclosure. It explains the pipeline flow, confirms text-based input instead of audio, and lists the returned components (bot response, verification status, tool calls, entities). It does not explicitly mention side effects or permissions, but the simulated nature is clear.

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 three sentences, front-loading the purpose, then the process, then the use case. Every sentence provides value without redundancy, making it concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description fully covers what the tool returns and the pipeline it runs. It also communicates the core use case and lack of real phone call, making it complete for the agent's decision-making.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The tool description does not add parameter-specific details beyond what is already in the schema, so the baseline score of 3 is appropriate.

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 simulates a voice conversation, runs the full voice pipeline (session → caller verification → prompt → skill dispatch → response), and returns each turn's details. It distinguishes itself from sibling test tools by focusing on end-to-end voice simulation via text instead of audio.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use this for testing voice-enabled solutions end-to-end without making a phone call. It provides clear context for when to use it, though it does not mention explicit 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.

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

No annotations provided, so description carries full burden. Mentions Core restart and two input modes, but omits destructive potential, auth requirements, rate limits, and error conditions common to mutation tools.

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 efficient sentences with no redundancy. Every word adds value. Front-loaded with key purpose and constraint.

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. Covers purpose, modes, and sibling differentiation. Could clarify exclusivity of github and files, and add result expectations. Still fairly complete for a 4-param tool.

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 covers 100% of parameters. Description adds context about github vs files modes and example connector ID, but does not significantly extend schema information. Baseline 3 is appropriate.

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 specifies uploading connector code to Core and restarting without redeploying skills, clearly distinguishing from sibling ateam_build_and_run. Includes examples (server.js, UI assets, plugins) and alternative input modes.

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 contrasts with ateam_build_and_run for connector-only changes, guiding when to use. Lacks explicit when-not-to-use scenarios, but context is clear.

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?

Even though no annotations are present, the description fully discloses read-only behavior ('does NOT trigger a deploy'), defines exact return structure (ok, drifts with kinds), and explains drift cause. This is strong behavioral transparency for a no-annotation tool.

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 well-structured with a leading one-sentence summary, bulleted return format, and a short implementation note. All sections earn their place; there is no fluff or redundancy.

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 is provided, so the description compensates by detailing both success and failure return values including drift kinds. It also provides use-case context and sibling sequencing, making it fully self-contained for a tool of this complexity.

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?

Only one parameter, solution_id, is already fully described in the schema as 'The solution ID to verify' (100% coverage). The description adds no further parameter semantics beyond using the phrase 'for a solution', so baseline 3 is appropriate.

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 uses specific verb 'Check that ... are in sync' and identifies the exact resource (Builder filesystem state vs GitHub state). The phrase 'Read-only probe — does NOT trigger a deploy' clarifies its non-mutating nature, distinguishing it from deploy/update tools like ateam_redeploy or ateam_github_patch.

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 instructs to 'Run after a series of ateam_github_patch calls' and before 'ateam_build_and_run', providing clear temporal context. It also contrasts with boot-sync healing, implying when early verification is valuable and when it is unnecessary.

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