ateam-mcp

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?

With no annotations provided, the description carries full burden and does so thoroughly. It explains the special semantics of chain_done (true only when ENTIRE chain is terminal), the meaning of pending_question (assistant waiting on user), and the performance characteristic ('cheaply'). This goes beyond simple operation disclosure.

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 and front-loaded with the key information, then provides usage context, then a practical loop. Each sentence contributes value without waste, offering rich guidance in a compact form.

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

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

Despite having no output schema, the description adequately enumerates the return fields (chain_status, chain_done, pending_question, result, progress line) and explains the loop termination conditions. This fully equips an agent to use the tool correctly without needing to discover behavior from elsewhere.

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 of the single parameter chain_id, including its source and that any job id works. The description adds no new parameter information beyond what the schema states, 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 function: returning the whole-chain aggregate status (chain_status, chain_done, pending_question, result, progress line) given a chain_id. It distinguishes itself from the sibling tool ateam_get_chain, which returns the full tree, making the purpose unambiguous.

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

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

Explicitly tells when to use this tool ('poll on a loop after ateam_conversation') and when NOT to use the alternative ('NOT ateam_get_chain — too heavy for periodic polling'). Provides concrete loop instructions (poll every ~2s until chain_done or pending_question), making usage crystal 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 fully discloses behavioral traits: it's ALWAYS ASYNC and returns a chain_id immediately, the reply is not in the response, and a conversation can run for minutes. It also explains the difference between chain and job termination and identifies which polling endpoint is cheap vs heavy. This goes far beyond typical descriptions.

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

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

Every sentence contributes critical information: purpose, async behavior, polling strategy, and multi-turn context. The description is longer than typical but each part earns its place and is logically structured in short paragraphs. 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?

Despite having no output schema, the description explains the return (chain_id), how to obtain final results (poll ateam_chain_status, use ateam_get_chain once at end), and how to handle multi-turn. For a tool with async complexity and interaction with sibling tools, this is thoroughly 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 covers all parameters so baseline is 3. The description adds meaning over the schema by explaining actor_id's role in multi-turn continuity, giving example message content, and clarifying that solution_id identifies the deployed solution. It doesn't repeat schema text verbatim, adding practical semantics.

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: 'Send a chat message to a deployed solution.' It specifies the resource (deployed solution), the verb (send), and adds a key differentiator ('No skill_id needed — the system auto-routes'). This distinguishes it from sibling tools like ateam_chain_status and ateam_get_chain.

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: never poll by job, poll by chain using ateam_chain_status, use ateam_get_chain only once at the end, and pass actor_id for multi-turn. It even names alternative tools and when to use them, which is excellent.

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?

Despite no annotations, the description thoroughly discloses critical behaviors: rendering is not automatic, the plugin must be advertised in the connector, and scaffold merges into existing connector. It warns about hardcoded lists and provides verification steps.

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 paragraphs and a prominent warning. Each sentence conveys necessary information for a complex scaffolding tool, so it earns a 4 rather than a 5 due to slight verbosity.

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 full workflow: scaffolding, manifest generation, deployment prerequisites, verification, and integration into the solution. It accounts for both GitHub-backed and repo-less tenants, making it highly 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 schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds valuable semantics for 'kind' (explaining default 'adaptive') and gives a concrete example for 'plugin_name', raising the score to 4.

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 ('Scaffold') and resource ('UI plugin inside an existing connector'). It distinguishes from sibling tools 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 clear context on when to use different kind values ('iframe' for web-only, 'rn' for mobile-only, 'adaptive' for both). It also gives follow-up steps (declaring ui_plugins) and verification methods, but does not explicitly state exclusions or 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?

With no annotations provided, the description compensates fully by disclosing cascading skill failures, reference cleanup in solution and skill definitions, mcp-store file removal, GitHub preservation, and resurrection via ateam_build_and_run. This is rich behavioral context beyond the schema.

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 dense but each sentence earns its place, covering cascading effects, cleanup scope, preservation, and resurrection. The use of emojis and semicolons improves readability, though it could be slightly more streamlined.

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 destructive nature and lack of output schema, the description is exceptionally complete: it explains what is deleted, what is preserved, required confirmation, and recovery path. No significant gaps remain.

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 extra meaning by specifying that confirm must be exactly true and explaining the refusal behavior with a recovery hint, which is not in the schema.

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

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

The description clearly states the tool 'Stops and deletes the connector from A-Team Core' and details its cascading effects. It distinguishes itself from sibling deletion tools like ateam_delete_skill and ateam_delete_solution by targeting connectors specifically.

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 permanent connector removal and warns of cascading failures, but it does not explicitly state when to use it versus alternatives or provide exclusion scenarios. The confirm requirement is clearly noted, but no alternative tools 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 carries full burden and exceeds it. It discloses multiple side effects (process kill, registry unregister, Mongo delete, array removals, FS file deletion), the confirmation requirement, and the recovery mechanism. This is exemplary transparency for a destructive 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, well-structured paragraph that front-loads the irreversible warning, lists effects, then requires confirm, and ends with recovery. Every sentence serves a purpose; the length is justified by the tool's high-stakes nature.

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, irreversible, no-output-schema tool, the description is exceptionally complete. It covers behavior, prerequisites (confirm:true), side effects, and recovery. It does not detail the return value, but that is not critical for a delete operation and the other contextual gaps are fully addressed.

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. The description adds critical context beyond the schema by explaining that confirm must be exactly true and that missing/false values trigger a refusal with a recovery hint. This reinforces the confirm semantic and clarifies the destructive consequences.

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 that this tool deletes a skill with specific destructive effects: kills the MCP process, unregisters from the skill registry, deletes the Mongo record, removes from solution.skills[] and linked_skills, and deletes files from Builder FS. This specific verb+resource pair distinguishes it from siblings like ateam_delete_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 implies when to use: for permanently deleting a skill, with strong warnings about irreversibility. It provides a recovery path via ateam_github_pull and notes there is no per-skill restore, which guides against casual use. However, it does not explicitly state alternatives or 'when not to use' beyond the destructive nature.

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

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

With no annotations, the description carries the full burden and excels: it discloses irreversibility, exactly what is destroyed, mandatory confirmation parameters, and recovery via GitHub. This is comprehensive and prevents misuse.

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 three sentences, front-loaded with a warning, then requirements, then recovery. Every sentence adds value and there is 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 covers the critical context: destructive scope, safety rails, and recovery. However, it does not mention the return value or whether deletion is synchronous, which could be relevant for an agent. The lack of an output schema makes this a minor gap.

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

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

The schema already documents all three parameters with 100% coverage, including the requirement that `confirm` must be true and `confirm_solution_id` must match `solution_id`. The description repeats these constraints but does not add new parameter semantics beyond what the schema provides.

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

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

The description explicitly states the tool deletes a solution, specifying exactly what gets destroyed: Mongo state, MCP processes, and Builder FS for the whole solution and every skill. This distinguishes it from sibling delete tools like `ateam_delete_skill` by clarifying the full scope.

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 recovery path (`ateam_github_pull`) and recommends it over re-deploying from memory, which helps the agent understand an alternative. However, it does not explicitly state when to use this tool vs. other mutation tools (e.g., `ateam_redeploy`), 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 full burden and discloses statelessness, advisory-only nature, and that it returns pointers/missing/lifecycle hints. It explains how to use design_state and that results are pointers, not mutations, though it doesn't detail output structure.

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 dense but well-structured, front-loading the purpose with 'CONSULT THIS DURING DESIGN' and then detailing outputs, advisory nature, and statelessness. Though long, each sentence adds distinct value and the tool's complexity justifies the length.

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

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

For a tool with no annotations or output schema, the description covers when to use, what it returns (pointers, missing, lifecycle), how to call (design_state, stateless), and constraints (advisory only). It lacks an explicit return structure, but the pointer descriptions and references to ateam_get_spec sufficiently guide an agent.

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

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

Schema has 100% coverage, so baseline is 3; the description adds semantics by explaining design_state as 'the design so far' and instructing to pass {} at the start. It also ties goal to 'Describe what you're building' with an example, going beyond 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 is a design advisor to consult during design, returning pointers to platform capabilities, missing hints, and lifecycle hints. It distinguishes itself from siblings by directing users to ateam_get_spec and other tools for follow-up, reinforcing its advisory role.

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 says 'before and while you design a skill/solution' and 'consult it as often as you like as the design evolves.' It also sets a boundary with 'ADVISORY ONLY — you decide and own the design,' though it doesn't name alternative tools for design advice beyond pointing to specs.

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 carries the transparency burden. It discloses auth behavior (forwards api_key, tenant/actor scoping), the walking-up behavior for non-root job IDs, and the detailed structure of both response shapes, including field names and semantics.

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 dense but every sentence adds value. It is logically organized with a high-level purpose, use-case, response shapes, sibling differentiation, and auth note. Bullet-like formatting aids readability despite the length.

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

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

There is no output schema, so the description compensates by detailing the exact response structures (chainJobs and executionSteps) with field names and relationships. Combined with auth and edge-case behavior, the description is fully sufficient for an agent to understand inputs, outputs, and constraints.

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%, but the description adds meaningful context beyond the schema: job_id can be any job inside the chain (Core walks up to root), and skill_slug is optional but speeds up storage lookup. These behavioral details are not present in the schema.

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

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

The description opens with a specific verb ('Inspect') and resource ('full chain tree for any job'), and immediately distinguishes itself from sibling ateam_test_status by purpose. This makes the tool's function unmistakable 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?

Explicitly states when to use the tool ('when a chain has already run and you want to analyze the structure'), explains the two response shapes, and contrasts with ateam_test_status for live polling. It also notes auth scoping, giving clear prerequisites 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 of disclosure. It reveals the manifest-only behavior when path is omitted, warns about the ~50KB output truncation limit, and advises reading files one at a time. This is vital operational detail that goes well beyond the schema.

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 concise sentences: the first delivers the core purpose, the second provides actionable usage guidance. Every word adds value, with no preamble 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?

For a simple 3-parameter read tool with no output schema, the description adequately explains return behavior (manifest vs content), the truncation limitation, and the recommended workflow. It is complete 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?

Schema description coverage is 100%, and the schema itself provides detailed parameter descriptions including the truncation caveat in the path field. The description adds little parameter-specific context beyond 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 reads source code files of a deployed MCP connector and gives examples (server.js, package.json). It distinguishes itself from other tools by specifying the mcp_store location and the 'read before modifying' intent.

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 instructs to use this tool BEFORE patching or rewriting a connector, giving clear when-to-use guidance. While it doesn't name alternative tools, the 'read current code first' directive implies the appropriate sequencing and purpose.

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 burden of behavioral disclosure. It adds that examples 'pass validation', implying a quality guarantee, but does not describe return format, pagination, or any side effects. For a read-only example fetcher, this is 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?

The description is two short sentences, front-loaded with the main action and purpose. Every sentence 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?

Despite having no output schema, the tool is simple with one fully documented parameter. The description explains what to get and why, and the schema explains the type parameter in enough detail. There is a minor gap in not explaining what the returned examples look like or how to use them beyond 'study these', but for a simple retrieval 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 input schema provides 100% coverage of the single parameter 'type', including a detailed description of each enum value. The description adds no additional parameter semantics, 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 retrieves complete working examples that pass validation, which is a specific verb+resource combination. It does not explicitly distinguish from sibling getter tools like ateam_get_solution or ateam_get_spec, but the focus on 'examples' is a distinct enough purpose that an agent would understand what it does.

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' gives clear context for when to use this tool (before building anything else). It does not mention alternative tools or when not to use it, but the guidance is sufficient for a simple retrieval 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 the full burden. It frames the tool as a read operation, and parameter descriptions disclose paging, truncation, and sectioning behavior. However, the 'validate' and 'connectors_health' views' side effects or behavioral implications are not addressed in the main description.

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

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

The main description is two concise sentences that front-load the purpose. The parameter descriptions are lengthy but provide necessary details for paging and sections; overall structure is clean.

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 6 parameters and no output schema, the description and parameter schema cover the main behaviors: view selection, paging, section filtering, and skill-specific reads. Missing return format details are somewhat compensated for by paging instructions but could be more 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 descriptions cover 100% of parameters with detailed explanations, so the baseline is 3. The main description adds a summary of available views but no new meaning beyond the schema's enum 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 'Read solution state — definition, skills, health, status, or export' clearly identifies the action and resource, listing the inspectable views. It does not explicitly distinguish it from sibling read tools like ateam_show_solution_minimal or ateam_status_all, but the scope is 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 states 'Use this to inspect deployed solutions,' providing a clear use case. It does not mention exclusions or alternative tools in the main description, though the 'section' parameter description references ateam_show_skill_minimal as an alternative for a slim view.

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 of behavioral disclosure. It reveals that the full spec is large, section returns smaller parts, and specifies what each topic returns (e.g., 'adas.* helper namespace reference'). It does not describe output format, but as a read-only retrieval tool this is acceptable.

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

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

The description is long but every sentence serves a purpose: it front-loads the core purpose, covers query options, then provides two targeted usage recommendations. The structure (general → specific scenarios) makes it easy to scan, and no sentence is wasted.

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 (3 params, 2 enums, many topic options), the description is remarkably complete. It covers when to fetch which topic, prerequisites (bootstrap), alternatives, and the relationship to the widget catalog. No output schema exists, but the description adequately conveys what content each fetch returns.

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 highly detailed parameter descriptions that already explain each topic, the section caveat, and search semantics. The tool description largely mirrors the schema's content, adding only minimal context (e.g., '5-10x larger / brittler scripts'), so it adds little beyond the structured schema.

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

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

The description opens with a clear verb and resource: 'Get the A-Team specification — schemas, validation rules, system tools, agent guides, and templates.' It explicitly differentiates from the sibling ateam_get_widget_catalog by pointing users there for the live widget catalog, satisfying the sibling-distinction requirement.

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 strong usage context: 'Start here after bootstrap,' suggests using 'section' for smaller payloads and 'search' for targeted queries, and explicitly names an alternative tool ('use ateam_get_widget_catalog instead'). It also gives scenario-based recommendations for 'python_helpers' and 'widgets'.

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 that the catalog reflects live tenant deployment (not spec), explains the auth model (forwards api_key, no master-secret, tenant scope pinned), and details the three origin types. It does not explicitly state it's read-only, but 'Get' plus the factual tone strongly imply so. Minor gaps like rate limits are not mentioned, but overall the behavior is well clarified.

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

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

The description is well-structured with clear sections (purpose, usage, origins, auth) and front-loads the key value proposition. It is slightly longer than strictly necessary, but every sentence provides useful context and the bullet list for origins aids scanability. 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?

For a tool with no output schema and four optional parameters, the description covers the return content (paste-ready how_to_use blocks with specific fields), usage context, origin semantics, and auth behavior. It lacks a detailed return schema, but the description provides enough for an agent to understand the tool's output shape. The tool is simple enough that 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?

Schema description coverage is 100%, so the input schema already fully documents all four parameters with detailed explanations. The description adds context about the how_to_use block and origins, but does not add meaning beyond the schema for the parameters themselves. This meets the baseline for high coverage without extra contribution.

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 with a specific verb ('Get') and resource ('live catalog of widgets (UI plugins) available in this tenant's solution'). It enumerates what is returned (platform/solution/skill widgets with how_to_use blocks) and explicitly distinguishes itself from the related ateam_get_spec tool, making its scope unambiguous.

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

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

It explicitly states when to use this tool ('Use this when wiring widgets into a skill or solution') and provides a clear alternative ('for the spec itself, use ateam_get_spec topic=\"widgets\"'). It also emphasizes real-time deployment status versus abstract spec, which helps the agent choose correctly.

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?

With no annotations provided, the description carries the full burden. It discloses default behavior (dev vs main), edge case (ahead_by: 0), and the ability to override base/head. It implies a read-only diff operation but does not explicitly confirm no side effects or mention permissions/rate limits.

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 a clear lead sentence and a bulleted list of use cases. It is not excessively verbose, though 'PRE-FLIGHT' in all caps is somewhat stylistic but acceptable. Every sentence adds useful context.

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 core use case, defaults, an important edge case, and how it relates to promote. It does not fully describe the return structure beyond 'commits and files' and 'ahead_by', but it is reasonably complete for a diff-check tool in a larger workflow.

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 parameter descriptions already explain base/head defaults and direction. The tool description reinforces the defaults and mentions override capability, but adds no substantial new meaning beyond what the input 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 uses a specific verb ('Compares') and clearly identifies the resource (branches/tags/commits) and purpose ('PRE-FLIGHT BEFORE PROMOTE'). It distinguishes itself from siblings like ateam_github_promote by explicitly stating it shows what would ship if promote were called next.

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 'Use this when you want to' list with concrete scenarios: reviewing changes before promoting, checking if dev is ahead, and inspecting arbitrary comparisons. However, it does not explicitly state when not to use this tool or name alternative comparison 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 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It covers key traits: default branch (dev), safety (writes don't touch prod), commit behavior, and the requirement for exact match in search/replace. It does not mention whether the commit is pushed or remains local, which could be relevant given sibling push/pull tools, but overall it provides substantial transparency beyond what a schema would.

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 fairly long but well-organized with numbered modes and a branch-safety note. It front-loads the core purpose and uses whitespace/line breaks for readability. Some redundancy exists (e.g., 'Always use search/replace for large files' reiterates 'preferred for large files'), but every sentence contributes actionable information. Slightly over-specific in places but still efficient.

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

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

For a tool with 7 parameters and no output schema, this description is remarkably complete. It explains the two modes, when to use each, preconditions (read first), branch safety default, and the relationship to sibling tools (promote for shipping, read for exact text). It also covers edge cases like 'emergency hotfixes' and large-file guidance, leaving little ambiguity about 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?

The input schema covers all 7 parameters with descriptions (100% coverage), so the baseline is 3. The description adds meaning by explaining the two operational modes that map to parameters: mode 1 uses 'content' for full-file replacement, mode 2 uses 'search' + 'replace' for surgical edits. It also adds practical guidance (e.g., file size threshold for choosing mode), which elevates the semantics beyond the schema 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's purpose: 'Edit a file in the solution's GitHub repo and commit.' It provides a specific verb (edit), resource (file in GitHub repo), and action (commit), which distinguishes it from siblings like ateam_github_read (read-only) and ateam_github_promote (branch promotion). The two modes logically expand on the main 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 explicitly tells the user when to use each mode and provides alternative tools: 'Always use search/replace for large files (>5KB)', 'Always read the file first with ateam_github_read', and 'Use ateam_github_promote to ship dev→main'. It also specifies when to use ref:'main' (emergency hotfixes), giving clear usage context and exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses side effects (auto-tagging), dry-run preview behavior, merge-conflict return code 409, and the manual resolution path, which goes well beyond what the schema or annotations provide.

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

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

The description is compact and front-loaded with the headline 'SHIP DEV TO PROD', followed by a clear summary, a numbered workflow, and edge-case notes. Every sentence contributes useful information without unnecessary 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 mutable operation with 4 parameters, no annotations, and no output schema, the description covers purpose, when to use it, workflow ordering, dry-run behavior, and conflict handling. It gives an agent enough context 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 description coverage is 100%, with each parameter already having clear meaning. The description mainly restates the dry_run behavior and adds some workflow context, but does not significantly extend parameter semantics beyond the high baseline.

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

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

The description opens with 'SHIP DEV TO PROD' and states 'Merges the dev branch into main and auto-tags...' which is a specific verb+resource. It clearly distinguishes this from sibling tools like ateam_github_patch (writes to dev) and ateam_github_rollback.

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 after testing your dev work, when you're ready to deploy changes to production' and provides a numbered workflow with ateam_github_patch and ateam_build_and_run. This makes the ideal usage context and relationship to alternatives 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 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 must carry the full behavioral burden. It discloses that the tool returns file content, defaults to 'main' (deployed/prod state), and allows a 'ref' parameter to access in-progress work. This gives the agent enough understanding of behavior, though it doesn't mention error cases or non-destructive aspects explicitly; 'read' strongly implies read-only.

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 the core purpose, and every sentence adds value: purpose, use cases, and branch behavior. There is no wasted wording or repetition of obvious 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 file-read tool with a fully described schema and no output schema, the description is complete. It clearly states what the tool does, what it returns, which parameters matter (especially 'ref'), and gives examples of intended use. The agent has enough context to select and invoke the tool correctly without needing additional details.

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% for all three parameters, so the baseline is 3. The description adds a bit of context by framing 'main' as deployed/prod and 'dev' as in-progress, but this largely repeats the schema's own parameter descriptions. It does not add substantial new meaning 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 starts with a specific verb and resource: 'Read any file from a solution's GitHub repo.' It clearly distinguishes this tool from sibling tools by emphasizing it reads any versioned file, including connector source code and skill definitions, and by noting the default 'main' branch and the ability to use 'dev' for in-progress work.

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 usage context: 'Use this to read connector source code, skill definitions, or any versioned file.' It also explains the branch semantics (default main vs ref 'dev'), which tells the agent when to read deployed/prod state vs in-progress work. It doesn't explicitly name alternative tools for exclusions, but the guidance is specific and sufficient.

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?

With no annotations, the description carries the full burden. It discloses merge-by-default behavior, refusal of bare array writes to prevent sibling loss, suffix-based array operations (_push/_delete/_update), local redeploy in both source modes, and output-size limits with `include_definition`. This is far beyond basic read/write safety.

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 justifiably so given the tool's complexity. It is well-structured with headings (OPERATIONS, SOLUTION-LEVEL EXAMPLES, SKILL-LEVEL EXAMPLES, PREVIEW) and front-loaded with the core purpose. Some repetition exists between the operations list and examples, but each section adds necessary context for safe use.

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 tool with 8 parameters, nested objects, no output schema, and multiple behavioral traps (merge-by-default, source modes, re-testing), the description covers usage, edge cases, preview, output control, and parameter semantics. It even explains the 'Redeploy is local in both modes' nuance and the output truncation risk with `include_definition`. No significant gaps remain.

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%, but the description adds substantial value beyond the schema. It explains dot notation for nested scalars, array operation suffixes, provides concrete examples for `updates`, clarifies the `dry_run` diff output fields, and explains the `_replace` opt-in for full-array replacement. This goes well beyond the baseline for high schema coverage.

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

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

The description opens with a precise verb+resource statement: 'Surgically update ANY field in a skill or solution definition, redeploy, and optionally re-test' — this clearly distinguishes it as an update/patch tool rather than a delete, read, or test tool. It also differentiates from siblings like `ateam_delete_skill` and `ateam_redeploy` by combining patch+redeploy+test in one call.

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 extensive usage guidance: detailed solution-level and skill-level examples, a clear warning about merge-by-default (bare array writes are refused), and a when-not directive for `source='local'` ('Use local ONLY for a repo-less bootstrap tenant... never a fallback'). It also recommends `dry_run:true` before destructive-looking edits.

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 carries the full burden. It explicitly states 'Read-only' to signal no side effects, and describes the output shape (most relevant doc chunks with topic and heading). It doesn't mention authentication or rate limits, but for a search 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?

The description is four sentences, each earning its place: core purpose, behavior, usage guidance, and safety hint. It is front-loaded with the primary function and uses clear, concise language with no 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?

For a two-parameter search tool with full schema coverage and no output schema, the description covers what it does, when to use it, what it returns, how to follow up, and its read-only nature. It is sufficiently complete 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces the query's natural-language nature and provides example usage, but top_k's meaning and default/max are already fully covered by the schema, so the description adds minimal extra 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 clearly states the tool performs semantic search over the full ateam platform /spec documentation, with specific verbs and resource scope. It distinguishes itself from sibling tools by positioning as the deep fallback behind ateam_design_advisor and explicitly mentions returning doc chunks with topic and heading.

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 when-to-use guidance: 'Use this when the advisor's pointer isn't enough, or for details/examples on anything.' It also names the follow-up tool ateam_get_spec, providing an alternative path, and excludes curated-capability-only usage.

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

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

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 carries the full burden. It does disclose a key behavior (stopping at the next iteration boundary) and flags the tool as 'Advanced,' but it omits whether the abort is irreversible, what happens to partial results, or any permission requirements. For a destructive action like abort, this is insufficient.

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 two sentences that front-load the main purpose ('Abort a running skill test') and add a useful behavioral note plus an 'Advanced' flag. Every word earns its place, with no 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?

For a simple abort tool with three ID parameters and no output schema, the description covers the core action and a key behavior. However, it lacks context about prerequisites (e.g., the test must be running), potential error conditions, or what happens after the abort. It is minimally viable but not fully complete.

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

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

The input schema provides descriptions for all three parameters (job_id, skill_id, solution_id) at 100% coverage. The tool description itself adds no additional parameter context beyond what the schema already gives. Per the baseline rule for high schema coverage, a 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 'Abort a running skill test' with a specific verb and resource. It also notes it stops at the next iteration boundary, which further defines the scope. This distinguishes it from sibling test tools like ateam_test_status or 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 usage is implied: it is for aborting a running skill test. However, there is no explicit guidance on when not to use it or mention of alternative tools for related operations (e.g., checking test status). The context is clear enough but lacks exclusions or direct comparisons.

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?

With no annotations, the description takes on full responsibility for behavioral disclosure. It thoroughly explains the wait modes (root, chain, never), the legacy wait parameter mapping, and the response.chain structure including chainJobs[] and executionSteps[]. However, it does not mention potential side effects of executing the skill or error handling, which prevents a perfect score.

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 and appropriately sized: a one-sentence purpose, a bulleted list for wait modes, and a brief legacy note. No wasted words; every sentence contributes essential information.

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

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

Even without an output schema, the description tells the user exactly what to expect in each wait mode: a single-job result for 'root', the full chain tree with chainJobs[] and executionSteps[] for 'chain', and a job_id for 'never'. It also covers legacy behavior and the timeout clamping in the schema, making it complete for a 7-parameter 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?

The input schema already provides 100% parameter coverage, but the description adds meaningful semantics for the wait_for/wait parameters: 'root' as back-compat default, 'chain' waiting for every job recursively, and legacy wait:false/true equivalences. This goes beyond the schema's enum descriptions, adding significant 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 clearly states the tool's purpose: 'Send a test message to a deployed skill and get the execution result.' This is a specific verb+resource+outcome that distinguishes it from siblings like ateam_test_status (which polls) and ateam_test_connector (tests connectors).

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 usage guidance: 'Use when testing multi-skill flows' for wait_for:'chain', contrasts root vs chain, and names ateam_test_status as the polling alternative for wait:'never'. This clearly communicates when and how to use the tool.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses the data returned, the status values (running/completed/failed), and that include_chain 'Costs one extra Core call.' It does not explicitly state non-destructiveness or mention rate limits, but for a polling tool the behavioral envelope is well 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 tight paragraphs. The first states what the tool does and returns in one sentence. The second explains the optional include_chain and its use case in two sentences. Every sentence adds value; 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?

For a 4-parameter tool with no output schema and no annotations, the description covers the essential context: what is returned, when to use the optional parameter, and the alternative pattern. It doesn't detail error conditions or timeouts, but the core usage is clear and complete enough for an agent.

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 meaningful context beyond the schema by explaining why include_chain exists (multi-skill snapshot) and how it relates to job_id (returned by ateam_test_skill). This elevates it above the schema-only minimum.

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 ('Poll') and resource ('async skill test'), and lists the exact return values (iteration count, tool call steps, status, result). It distinguishes itself from sibling tools like ateam_test_skill (which launches) and ateam_chain_status (which focuses on chains) by explicitly scoping to test progress and offering optional chain inclusion.

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 for when to use include_chain:true ('Use when this job dispatched askAnySkill subcalls...') and provides an alternative ('instead of polling each child job_id separately'). However, it does not explicitly mention other sibling polling/status tools, so it stops short of a full when-not-to-use breakdown.

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?

With no annotations provided, the description carries the full burden and exceeds expectations. It discloses default ref behavior, merge semantics, refusal to nuke without a GitHub base, and even historical bugs that shaped the design. This gives the agent a precise mental model of the tool's 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 front-loaded with the core action and then uses structured bullets for modes and traps. It is longer than strictly necessary, but every sentence adds operational value; the common traps section is arguably essential for safe usage. Slight redundancy in the modes section could be trimmed.

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, no annotations, and no output schema, the description is remarkably complete. It covers all parameters, their combinations, default values, historical pitfalls, and failure modes (e.g., refusing to merge without a GitHub base). There is no ambiguity about what the tool will do.

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 significant meaning beyond individual parameter docs by explaining how parameters interact in each mode (e.g., github:true+files:[] vs files:[] alone). It clarifies defaults and consequences that the schema alone does not convey, such as the 'silent-main default' trap.

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 first sentence states a specific verb and resource: 'Upload connector code to Core and restart — WITHOUT redeploying skills.' It clearly distinguishes this tool from deployment/redeployment siblings by emphasizing the no-redeploy aspect. The scope is further clarified with merge vs replace 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?

The description explicitly enumerates four modes of operation with exact parameter combinations, giving clear guidance on how to achieve different goals. However, it does not explicitly name sibling tools or state when NOT to use this tool, instead relying on the mode descriptions to imply 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 provided, the description carries the full burden. It discloses that the tool returns actual live state ('the truth', 'not a generic warning'), details what it checks, and notes that it routes through the Builder rather than a direct Core call. This adds significant behavioral context beyond a simple 'verify' label, though it doesn't explicitly discuss side effects, permissions, or output format.

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 and well-structured. It opens with a compelling 'ONE call' hook, then explains what it returns, when to use it, and why it's reliable. 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 tool's simplicity (one parameter, no output schema), the description is remarkably complete. It covers the tool's capability, usage timing, and technical routing, giving an agent everything needed to decide when and how to invoke it.

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 fully covers the single parameter (solution_id) with a clear description and 100% coverage. The tool description does not add additional parameter semantics, but the schema is sufficient, 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 specifies a clear verb ('returns') and resource ('REAL runtime end-state of a solution'), enumerating concrete checks (connectors connected, tools discovered, widgets rendering, skills deployed) and explicitly claims it identifies 'the EXACT failing gaps'. This distinguishes it from generic verification tools and sibling tools like ateam_status_all or ateam_verify_consistency.

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 usage context: 'Use this instead of guess-and-check after a deploy/patch'. This is a clear when-to-use directive. However, it does not name specific alternative tools or state when not to use it, so it falls short of a full 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?

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.