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?

There are no annotations, so the description carries the full behavioral disclosure burden. It does so well: it discloses cost/performance traits ('chip-quick', 'cheaply'), explains the precise semantics of chain_done, and warns that an individual job can finish while the chain is still running. This prevents a common polling mistake.

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 longer than minimal, but every sentence earns its place by enabling correct loop behavior. The key differentiator ('NOT ateam_get_chain') is front-loaded, and the ending gives a clear actionable sequence.

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?

Since there is no output schema, the description must explain return semantics in prose, and it does: chain_status, chain_done, pending_question, result, and a progress line. It also covers the full interaction lifecycle, from initial poll through termination and optional fallback to ateam_get_chain for detailed per-job data.

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 tool description reinforces that chain_id comes from ateam_conversation and that job_id aliases to the chain aggregate, but the schema already documents these relationships. There is no substantial new parameter meaning added in the 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 identifies the tool as a lightweight whole-chain status poll, naming the exact resource (chain_id from ateam_conversation) and the fields returned. It explicitly distinguishes itself from ateam_get_chain, so an agent can select it correctly without inspecting the sibling.

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

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

The description explicitly says when to use this tool ('poll on a loop after ateam_conversation') and when not to ('NOT ateam_get_chain'). It also gives a concrete polling recipe: call every ~2 seconds until chain_done or pending_question is set, then optionally fetch the full tree via ateam_get_chain.

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 present, the description carries the full behavioral burden, and it delivers: it explains that a connector can swallow errors and still return ok:true, that empty/zero data can look legitimate, that authentication failures may only be visible here, and the platform/HTTP limitation. This goes far beyond what the schema alone communicates.

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 longer than typical, but the extra length earns its place: the core statement is front-loaded, the real-world case makes the failure mode concrete, and the usage/limitation guidance is actionable. Slight redundancy such as emphasizing 'only place' twice could be tightened, but it remains well organized and purposeful.

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 debugging/log-reading tool with no annotations and no output schema, this description covers what an agent needs: what the tool does, when to reach for it, how to use the cursor for incremental reads, and which connector types are unsupported. The only minor omission is an explicit return-shape description, but the references to 'returned cursor' and stderr lines provide enough context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value beyond the schema by explaining the cursor workflow: 'Pass the returned `cursor` back as `since` to read only what is new since your last look, so you can bracket an action.' This clarifies the intended use of `since` in a way the schema does not.

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: 'Read what a connector process actually PRINTED to stderr.' It clearly distinguishes this from generic logs or execution logs by explaining that this is the only place an internal connector failure becomes visible, and even contrasts it with tools that return ok:true despite failures.

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 IT whenever a tool succeeds but the data is empty, wrong, or zero — that combination is the signature of a swallowed error.' It also states when NOT to expect this to work: 'Only stdio (solution) connectors stream stderr through Core; a platform/HTTP connector answers ok:false with a reason.' This clearly routes the agent.

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, the description carries full burden and excels: it discloses the CASCADING destructive effect, the durable repo deletion, the 2026-08-23 behavior change, the partial-failure reporting under `github`, and the confirm requirement. Nothing about the tool's side effects is hidden.

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

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

The text is long but front-loads the critical warning and then systematically covers effects, durability, alternative, and failure case. It is slightly verbose with historical detail, but every sentence contributes essential caveats for a destructive operation.

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

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

For a high-risk, cascading, no-output-schema tool with zero annotations, the description covers all key operational aspects: what will break, what gets deleted, how to preserve code, failure response semantics, and the required confirmation flag. An agent can safely invoke this tool with minimal ambiguity.

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

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

The schema already documents all three parameters with examples and a strict confirm rule (100% coverage), so the description adds little beyond re-emphasizing confirm:true. Baseline 3 applies because 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 states a precise verb and resource — 'Stops and deletes the connector from A-Team Core' — and enumerates the full scope (references, mcp-store files, source repo). It is unmistakably distinct from siblings like ateam_delete_skill or ateam_get_connector_source.

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 clearly frames when to use the tool: when a durable, cascading delete is intended, and explicitly routes to ateam_get_connector_source if the code must be kept. It also cautions against relying on the old resurrection path, giving an agent the context needed to decide between delete and preserve.

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 the full disclosure burden and does so thoroughly: it states that the tool is stateless, advisory-only, returns missing/lifecycle hints, and that a truncated reply means absence of a capability proves nothing. This is strong behavioral transparency.

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

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

The description is long but dense and front-loaded with the most important instruction. Every section earns its place, especially the truncation warning, but there is minor redundancy around consulting frequently and passing design_state, which keeps it from a perfect conciseness score.

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

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

Given there is no output schema, the description fully explains what to expect from the tool: capability pointers, spec topics, missing hints, lifecycle hints, and the truncated flag with follow-up actions. Nothing needed to invoke or interpret the tool correctly is missing.

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 modest operational value by explaining statelessness — pass the current design_state each call — and by framing goal as 'what you're building' in your own words, but it does not need to compensate for missing schema docs.

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 names a specific action (consult during design), a concrete deliverable (pointers to platform capabilities, spec topics, and tools to wire), and a clear advisory stance. It also distinguishes itself from siblings by routing to ateam_get_spec for reading and ateam_spec_search for searching.

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 when to use the tool (before and while designing a skill/solution) and how often (as the design evolves). It also handles alternatives: when truncated, narrow the goal or use ateam_spec_search before concluding a capability is missing.

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 covers auth/key forwarding, tenant scoping, and actor-level access restrictions. It also explains the two response shapes and the depth/relation semantics. This is substantial behavioral context beyond what the schema provides.

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 part is functional: purpose, output shape, differentiation, and auth/scoping are all distinct. The bullets keep the two response shapes scannable and the content is front-loaded with the core purpose. It earns its length.

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

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

No output schema exists, so the description compensates by enumerating chainJobs[] and executionSteps[] fields, including depth and relation semantics. It also covers auth and scoping constraints needed to call correctly. For a non-mutating inspection tool, nothing essential is missing.

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 all four parameters, so the baseline is 3. The tool description reinforces the preferred parameter (chain_id), explains why actor_id may be required, and notes the performance effect of omitting skill_slug. This adds modest extra context beyond the schema, though the parameter-specific load is mostly carried by 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 and resource — 'Inspect the full chain tree' rooted at chain_id — and itemizes exactly what the tool returns (chainJobs[] and executionSteps[]). It also explicitly contrasts itself with ateam_test_status, so an agent can distinguish it from a close sibling.

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

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

It states a precise trigger: 'Use when a chain has already run and you want to analyze the structure' and provides a direct alternative comparison: ateam_test_status is for live polling while get_chain is for post-hoc analysis. This is explicit when-to-use guidance.

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

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

With no annotations, the description carries the 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?

With no annotations, the description must carry the behavioral disclosure burden. It discloses the shape of returned data (recent jobs with traces, tool calls, errors, timing) and implies a read operation through 'Get', but does not mention auth needs, side-effect absence, or edge-case behavior beyond what the schema separately documents.

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 functional sentences plus a succinct '(Advanced.)' signal. The core purpose is front-loaded, and every clause adds either purpose, content, or usage context without 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?

For a 6-parameter read tool with no output schema and no annotations, the description plus the rich schema explanations give an agent what it needs to invoke the tool. It could be more complete about the expected return shape and how to obtain a job_id, but the stated contents and detailed parameter docs make it sufficient in practice.

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 six parameters, including the important actor_id requirement and chain_id preference. The main description adds no parameter-level meaning, so the high-coverage baseline of 3 applies.

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

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

The first sentence states a clear verb and resource: 'Get execution logs for a solution' and enumerates the log contents ('step traces, tool calls, errors, and timing'). This is unambiguous, though it does not explicitly contrast with sibling logging/status tools such as ateam_chain_status or ateam_connector_logs.

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?

'Essential for debugging what actually happened during skill execution' provides a clear use case. It does not specify when to prefer a sibling tool or list exclusions, but the debugging context is enough to guide 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, the description carries the behavioral disclosure burden. It states the read-only nature, bounded newest-first ordering, and the meaningful semantics of an empty list. It does not cover error conditions or authentication, but for a lightweight read tool this is substantial and useful context.

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

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

Every sentence delivers distinct value: purpose and ordering, when to call and why, entry content, and empty-list meaning. The description is front-loaded with the most important operational facts and has 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?

The description covers purpose, usage timing, output semantics, and entry structure despite having no output schema. It is slightly incomplete around failure modes and pagination behavior, but for an orientation-focused read tool the essentials are all 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?

Schema description coverage is 100%, so the schema already explains both solution_id and limit. The description reinforces the 'bounded' and 'newest first' aspects but does not add significant parameter-level meaning beyond the schema.

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

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

The description clearly identifies the tool as reading lessons learned by earlier runs, scoped to a solution, and notes it returns newest-first bounded results. It distinguishes itself from sibling tools like ateam_log_lesson and ateam_get_progress by stating it is the only thing that carries context across runs.

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 timing guidance: call during orientation, before planning. It also emphasizes the tool is cheap and uniquely carries cross-run context. It does not explicitly name alternatives or say when not to use a different tool, so it misses the top score on this dimension.

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 behavioral burden, and 'Get' reasonably implies a read-only operation. However, it does not mention auth enforcement, side effects, or how the optional job_id/chain_id 'deep analysis' paths change behavior; those details are left to 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 a single sentence that front-loads the action and resource, then uses a scannable comma-separated list of result categories. There is no filler or redundant restatement of the tool name.

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 gives useful output categories but, with no output schema and no annotations, it does not fully explain return format, filtering behavior, or access constraints. The rich parameter schema compensates for some of this, but the overall context is only partially self-contained.

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 tool description does not add parameter-level meaning, but the schema already documents solution_id, job_id, actor_id, chain_id, and skill_id in 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 uses a specific verb and resource ('Get execution metrics') and enumerates concrete content categories: timing, tool stats, bottlenecks, signals, and recommendations. It is clear but does not explicitly differentiate itself from sibling tools like ateam_get_execution_logs or ateam_get_progress.

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 no when-to-use or when-not-to-use guidance and names no alternatives. The only hint is '(Advanced.)', which signals caution but does not tell an agent when to choose this over sibling analytics or logging 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 must carry the behavioral burden, and it does well by disclosing that 'latest entry wins' and cautioning that ABSENT does not mean nothing was done, because the journal may predate a step or a run may have died before writing. It clearly frames the tool as a fast path rather than a source of truth. It does not discuss error conditions or auth, but the key interpretation pitfalls are covered.

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

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

The description is longer than average but each section earns its place: it front-loads the most critical instruction ('read it FIRST'), then states the return shape, then explains the non-obvious ABSENT semantics, and finally disambiguates from the sibling. There is no filler, and the warnings are essential rather than redundant.

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 there is no output schema and no annotations, the description does a strong job of covering what the tool returns, when to call it, how to interpret the returned status, and how it relates to ateam_get_lessons. It could still be more explicit about the exact shape of the step entries or verified values, but the essential guidance for correct invocation and interpretation 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?

Schema description coverage is 100%, and both parameters have explicit descriptions in the schema: solution_id is documented and limit has both a default and the note that steps is always complete. The description reinforces the semantics of limit by contrasting 'history entries' with the always-complete steps, but it does not add substantial meaning beyond the schema.

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

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

The description opens with a concrete statement of what the build has achieved and immediately states the tool returns 'CURRENT status per step (latest entry wins) plus recent history.' It also differentiates from the sibling ateam_get_lessons by explicitly framing this tool as recording what WORKS versus what BROKE, so an agent can distinguish them.

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 explicit when-to-use instructions: 'read it FIRST when continuing a run, before any orientation call,' and prescribes the action to take afterward: 'build only the steps that are ABSENT or not yet verified.' It also names the complementary alternative, ateam_get_lessons, and clarifies the division of responsibility.

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?

No annotations are present, so the description carries the burden. It does disclose useful behavioral traits — section returns something 'much smaller', python_helpers returns the adas.* namespace reference, widgets returns the widget spec — and warns about 5-10x larger/brittler scripts without it. However, it never states the actual output format, payload size, or any cost/rate characteristics of fetching the full spec, so an agent cannot fully anticipate the result.

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 front-loaded with the core purpose, and each paragraph covers a distinct decision point (basic use, python_helpers, widgets). It is somewhat redundant with the very detailed input-schema topic descriptions, but the redundancy reinforces rather than bloats. No irrelevant sentences.

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 rich schema and the absence of an output schema, the description provides enough to call the tool correctly: it identifies required context, topic-specific choices, narrowing mechanisms, and a sibling to use instead for live catalogs. The only notable omission is not spelling out that ateam_spec_search exists for cross-spec search, which would complete the routing picture.

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, but the description adds real usage semantics beyond the enum labels: it explains why python_helpers is needed for personas, what widgets returns for UI plugins, and how search/section narrow the result. This is more than the schema alone provides and materially helps an agent select correct parameter values.

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

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

The description opens with a specific verb and resource: 'Get the A-Team specification' and enumerates its contents (schemas, validation rules, system tools, agent guides, templates). It differentiates from ateam_get_widget_catalog by pointing to that sibling for live catalogs, but it does not distinguish itself from the adjacent ateam_spec_search sibling even though it tells users to use the 'search' parameter for cross-spec search. Clear, but not fully differentiating.

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?

Gives explicit when-to-use guidance: 'Start here after bootstrap', 'when designing a persona ... fetch topic=python_helpers', 'when wiring widgets ... fetch topic=widgets', and an explicit alternative for live widget inventory: 'use ateam_get_widget_catalog instead'. It does not cover when a dedicated search sibling (ateam_spec_search) would be preferable, which is a gap given the 'search' parameter advice.

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

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

With no annotations 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, the description carries the full burden and it succeeds richly. It discloses return values like ahead_by, behind_by, and status; explains the diverged state and its relation to a 409 conflict; clarifies that files[] lists differences rather than conflicts; and warns about deploy-generated data in solution.json and skills files.

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 longer than average but every sentence earns its place: the first line is a bold, scannable summary followed by structured bullets and a brief important note about deploy-generated data. It is front-loaded with the core comparison behavior and the promote tie-in, so an agent gets the key message immediately.

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

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

For a read-only diff tool with no output schema and no annotations, this description is nearly complete. It covers defaults, when to use, how to interpret return values, failure diagnosis, and known data quirks. The only minor omissions are general edge cases around invalid refs, but those are not critical given how much is already disclosed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful conceptual value beyond the schema by explaining that base/head can be overridden with arbitrary branches, tags, or commits, and by framing base as the target and head as the source in the promote workflow. It doesn't add much per-parameter syntax detail, but the added framing is useful.

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') with a clear resource and scope: dev vs main by default, showing exactly which commits and files ship with a promote. It explicitly orients the agent as a pre-flight check for ateam_github_promote, which clearly distinguishes it from the many sibling GitHub tools.

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

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

The description provides explicit when-to-use bullets: before promoting, to check if dev is ahead, to diagnose a failed promote, and for arbitrary branch comparisons. It even instructs the agent to ALWAYS call this after a promote failure before reporting to the user, which is strong, actionable usage guidance.

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

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

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?

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool commits changes, defaults to the dev branch, avoids touching prod, and has two distinct edit modes. It could go further by explaining what happens on failure or what the commit response looks like, but the core behavioral traits are 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?

The description is dense but well organized, starting with the core action and immediately presenting the two modes. Every section earns its place: mode selection, large-file guidance, prerequisite reading, branch safety, and promotion path. There is minimal redundancy given the amount of operational guidance packed in.

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 an 8-parameter mutation tool with no output schema and no annotations, the description covers the essential decisions: which mode to use, when to use each parameter group, the branch default, and the safe promotion workflow. It does not describe return values or error cases, but the provided guidance is sufficient for correct invocation in most scenarios.

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, but the description adds real value beyond the schema: it connects content to FULL FILE mode, connects search/replace to surgical edits, gives a concrete >5KB threshold, and explains that reading first ensures exact search text. This meaningfully enriches the parameters.

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: 'Edit a file in the solution's GitHub repo and commit.' It also clearly explains the two operating modes. However, it does not explicitly differentiate this tool from the closely named sibling ateam_github_write, so an agent could still hesitate about which tool to choose.

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, actionable guidance: use FULL FILE for new/small files, use SEARCH/REPLACE for large files, always read the file first with ateam_github_read, default to dev branch, use ateam_github_promote for dev→main, and pass ref:'main' only for emergency hotfixes. This is strong when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses the merge side effect, auto-tag format, dry-run behavior, and the 409 recovery path, giving the agent a clear model of what will happen and how failures should be handled.

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, then organized into workflow, dry-run, and conflict-handling blocks. Every sentence earns its place; although it is longer than average, there is no filler and the structure aids quick parsing.

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 deploy/promote tool with no annotations and no output schema, the description covers the normal path, the preview path, and the conflict escalation path. It also names the exact sibling tools and the order in which they should be used, making the tool callable in context.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description adds useful context about the tag format and dry-run behavior, but it does not materially add per-parameter semantics beyond what the schema provides, so the 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 'SHIP DEV TO PROD. Merges the dev branch into main and auto-tags...', naming a specific verb and resource. It also explicitly differentiates from siblings via the workflow: ateam_github_patch writes to dev, ateam_github_promote merges dev→main, and ateam_build_and_run deploys main.

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 states exactly when to use the tool: 'Use after testing your dev work, when you're ready to deploy changes to production.' It also gives the numbered workflow and explicit conflict-handling alternatives: call ateam_github_sync_from_main on a 409, retry promote, and only escalate to a human PR if a second 409 occurs.

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

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

No annotations are provided, so the description must carry the full burden. It discloses what files are read and that data feeds into the deploy pipeline, which is useful. However, it doesn't mention potential side effects (e.g., overwriting existing deployment), required permissions, or reversibility—leaving gaps in transparency.

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

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

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

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

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

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

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

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

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

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

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

The description opens with a clear, specific action: 'Deploy a solution FROM its GitHub repo.' It further clarifies the mechanism (reads .ateam/export.json + connector source) and distinguishes this tool from siblings like ateam_github_push and ateam_redeploy by explaining its role as pulling from GitHub to deploy.

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

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

The description provides explicit use cases: 'Use this to restore a previous version or deploy from GitHub as the source of truth.' This gives clear context for when to choose this tool, though it doesn't name alternative tools or state when not to use it.

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

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

With no annotations, the description carries the full burden. It discloses important behaviors: auto-creates the repo on first use and commits the full bundle atomically. However, it does not mention authentication requirements, remote conflict handling, or whether the push is a force push, leaving some gaps.

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

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

The description is three sentences, front-loaded with the core action. Each sentence provides distinct value: the primary function, key behaviors, and usage guidance. No redundant or filler content.

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

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

No output schema exists and annotations are absent, but the description covers inputs (via schema), side effects, and usage timing. It omits response/error details, but for a straightforward push operation, it is nearly complete.

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

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

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

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

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

The description clearly states the action ('Push') and resource ('current deployed solution to GitHub'), and adds unique context about auto-creating the repo and committing the full bundle atomically. This distinguishes it from sibling tools like ateam_github_pull or ateam_github_write.

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

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

The description explicitly tells when to use the tool: after ateam_build_and_run to version the solution, or anytime to snapshot the current state. It provides clear context but does not explicitly mention when not to use it or name alternatives beyond the referenced build tool.

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

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

No annotations are provided, so the description carries the full burden and uses it well: it discloses the git-mirror trap for solution.json and skill.json, deploy-time regeneration of connector-imported tools, the 29-vs-66 tools discrepancy, and the _ateam_representation field. This far exceeds typical read/write hints.

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 definition is front-loaded with a one-line purpose, then the ref workflow, then a clearly marked warning. The concrete example and _ateam_representation note earn their place because they prevent confident but incorrect reads; there is 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?

Given no output schema and no annotations, the description still equips an agent with purpose, ref semantics, the mirror-vs-runtime caveat, the representation field, and the correct fallback tool for runtime capability questions. A caller can use it correctly without needing sibling tool docs.

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?

Even though the input schema covers all four parameters, the description adds operational meaning: default main corresponds to prod state, passing ref: 'dev' reads in-progress work, and path examples map directly to intended uses. The branch-alias footgun is explained in the schema, while the main description reinforces the ref workflow.

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?

Opens with a specific verb and resource ('Read any file from a solution's GitHub repo') and immediately states the return value. It gives concrete use cases (connector source, skill definitions, versioned files) and heads off confusion with runtime tools by warning this is not runtime state. This clearly separates it from siblings 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?

Tells when to use it ('Use this to read connector source code, skill definitions, or any versioned file'), how to select a ref (main vs dev), and explicitly when not to use it: for runtime skill capability, call ateam_get_solution and 'never this tool.' The not-runtime-state warning provides a crisp exclusion criterion.

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 thoroughly explains the internal call to sync_from_main, the two-parent merge commit creation, the newest-wins conflict resolution heuristic, and the reporting of every decision. It even illustrates why this matters with a real-world example and the merge-base pitfall. This is exemplary transparency for a tool with no 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?

The description is long but every sentence earns its place. It opens with the core purpose, then usage triggers, then critical behavioral details, and ends with a who-needs-this note and a dry_run tip. The structure front-loads the essential usage decision and builds context logically. There is no filler or repetition, making it dense but perfectly scannable.

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 a complex operation (branch reconciliation), the description covers all necessary aspects: what it does, when to use it, how it resolves conflicts, why it behaves that way, and how to test it safely. It even explains the broader scenario of tenants needing this. An agent has enough to call it correctly and interpret the reported decisions. Nothing critical is missing.

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% (both parameters have descriptions), so the baseline is 3. The description adds specific context for dry_run: 'Pass dry_run:true to see the decisions before writing anything.' This goes beyond the schema's terse 'Report the per-file decisions without writing the merge commit' by clarifying it as a pre-flight check. For solution_id, the schema already says 'The solution ID,' and the description doesn't add much—but that's fine given full coverage. The extra dry_run nuance justifies a 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 opens with a precise verb-action pair: 'JOIN a diverged dev and main.' It clearly states the tool's purpose and differentiates it from siblings by referencing ateam_github_promote's specific return codes and explicitly contrasting with ateam_github_sync_from_main. An agent can immediately understand what the tool does and why it exists.

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 conditions for use: 'Use when ateam_github_promote returns PROMOTE_NEEDS_HUMAN or PROMOTE_PRECONDITION_FAILED.' It also instructs to 'TRY sync_from_main FIRST' and explains this tool calls it internally, escalating only on real conflicts. This provides a clear decision path and alternative, leaving no ambiguity about when to invoke it.

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

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

With no annotations, the description carries full 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 provided, the description carries full behavioral burden and does so thoroughly: it clarifies this is a real merge rather than a force, describes the dry_run behavior as change-free, and discloses that a 409 can also mean conflicting same-line edits. This goes well beyond a generic 'syncs branches' 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?

Although the description is longer than average, every sentence earns its place: purpose, trigger condition, workflow, dry-run safety, and conflict caveat are all present and front-loaded. The structure moves from most important usage information to edge-case caveats.

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 highly complete for a mutating sync tool: it covers when to use, workflow, dry-run behavior, and failure modes. It does not describe the success return payload, but in the absence of an output schema this is a minor gap given that the tool's effect ('dev is up to date with main') is clear from the purpose statement.

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 both parameters clearly. The description reinforces the 'call dry_run first' behavior but does not add significant new parameter-level meaning beyond what the schema provides, making the baseline 3 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 states a specific verb and resource ('merges main into dev') and explicitly distinguishes itself as the mirror of ateam_github_promote. An agent can immediately understand what this tool does and how it differs from related GitHub tools.

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

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

The description gives a precise trigger condition ('USE THIS WHEN PROMOTE RETURNS 409'), explains why promote alone cannot fix divergence, and provides a step-by-step workflow involving ateam_github_diff, this tool, and ateam_github_promote. It also explicitly warns when this tool is NOT appropriate (same-line conflicts requiring a human PR).

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 and handles it well. It discloses append-only behavior, server-side timestamping, the provenance caveat about null job_id/actor, the inability to trace lessons to runs, and the rule to keep errors verbatim.

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 longer than average, but nearly every sentence carries important guidance. The core purpose is front-loaded, and the caveats are organized in labeled paragraphs. Minor redundancy exists around the verbatim requirement, but it is not wasteful.

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

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

Given no annotations and no output schema, this description is remarkably complete: it explains when to log, what to log, how to choose kind, what not to include, and the append-only/provenance constraints. An agent has enough to call 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 the baseline is 3. The description adds real value beyond the schema by explaining the meaning of misleading_success, emphasizing verbatim error capture, and noting that 'worked' can legitimately be omitted when unknown.

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: 'Record ONE lesson this run learned, so the NEXT run does not relearn it.' It clearly distinguishes this logging tool from retrieval siblings like ateam_get_lessons and states the exact outcome it serves.

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 an explicit trigger condition ('the moment a tool misleads you AND you find a way through') and provides concrete guidance for choosing kind='misleading_success'. It also warns against logging theories or paraphrased errors, effectively saying when not to use the tool in a misleading way.

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 behavioral disclosure. It reveals no-update-path semantics ('latest wins'), the meaning of silence after regression, and the distinction between a deployment response and genuine verification — including a concrete failure example with a connector showing 9 tools but 401 storage calls.

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 lengthy but well-structured with short labeled sections and front-loaded core purpose. Every major paragraph earns its place through runtime evidence or actionable rules, though a tighter edit could reduce redundancy in the WHY section.

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 write-only journaling tool with five parameters and no output schema, the description is complete: it explains when to call, why it matters, how each status differs, what evidence is required for verified, and the replacement semantics. No essential operational detail is missing.

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?

Input schema coverage is 100%, so the baseline is 3. The description adds meaningful beyond-schema semantics: it explains the three statuses with examples, mandates verified_by for verified, defines the stable-slug requirement for step, and provides a verified_by format example. This meaningfully enriches the schema without repeating 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 precise verb and resource: 'Record that a build STEP is done, so a later run does not redo it.' It clearly distinguishes the tool from its read-side sibling ateam_get_progress, making the operation's scope immediately 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?

Usage is explicitly prescribed: 'Write it AS IT HAPPENS, never at the end', with a concrete reason grounded in how continuation runs fail. The description also instructs when to re-log (advancing statuses) and when to regress, leaving no ambiguity about timeliness or replacement behavior.

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 behavioral burden, and it excels: it discloses merge-by-default behavior, refusal of bare array writes, auto-degrade source handling, dry_run diff contents, non-blocking validation, and output-size truncation. It also warns that invalid definitions still save and that build_and_run will refuse to deploy them.

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 the tool is complex and the length is mostly justified. It is well-structured with headers, warnings, operation patterns, and target-specific examples, and the most safety-critical merge warning appears early. Minor redundancy and verbosity prevent a 5.

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

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

Given the tool's complexity and the absence of an output schema, the description covers the full calling context: target selection, update payloads, array pitfalls, preview/dry_run, source fallback, redeploy behavior, validation verdict, and response-size caveats. An agent has enough information to call this tool correctly and interpret its results.

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 operational meaning beyond the schema: dot-notation syntax, array suffix semantics, full-array replace opt-in, source enum fallback behavior, dry_run return fields, and include_definition's 50KB output-limit caveat. This is far more than the schema alone 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 first sentence states a specific verb and resource: surgically update any field in a skill or solution definition, then redeploy and optionally re-test. It clearly differentiates this from sibling GitHub patch, redeploy, and test tools by advertising the combined one-step 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 gives rich situational guidance: use dry_run before destructive-looking edits, prefer _push/_delete/_update suffixes, opt into full-array replace deliberately, and check validation incomplete_sections. It does not explicitly contrast with siblings like ateam_github_patch or ateam_redeploy, but the context is strong enough for an agent to choose appropriately.

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?

With no annotations provided, the description carries the full burden and discloses meaningful behavior: scope of destruction (whole chain vs a single job), side effects (handoffs keep running on job-level aborts), timing (stops at the next iteration boundary), and return content (which ones stopped). The '(Advanced.)' tag signals elevated risk, though reversibility and preconditions (test must be running) are unstated.

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

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

Three sentences with zero filler: purpose first, then the chain_id/job_id contrast, then the boundary behavior and risk flag. Every sentence earns its place and the key decision (which identifier to pass) is front-loaded.

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

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

The two abort modes are covered thoroughly, but the only required parameter is solution_id and the description never explains what passing solution_id alone does, nor is the return format (beyond 'which ones stopped') specified. With no output schema and no annotations, that is a real gap for a destructive control tool.

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

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

Schema description coverage is 100% and the parameter descriptions are already rich — chain_id is called 'THE EXECUTION'S IDENTITY' and job_id warns that aborting the root leaves handoffs running. The main description re-echoes the chain/job distinction rather than adding new per-parameter meaning, so the 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?

States a specific verb and resource ('Abort a running test') and immediately differentiates the two abort scopes: chain_id kills the whole run, job_id stops a single job only. This distinguishes it from the test-family siblings (ateam_test_status checks status, ateam_test_skill runs a skill) without needing their schemas.

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 the agent which mode to use when: chain_id aborts the whole run, job_id stops one job while leaving handoffs running, and the schema reinforces the preference ('Prefer chain_id'). It does not, however, state when not to abort or route to an alternative such as ateam_test_status, so it stops short of 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 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?

No annotations are provided, so the description carries the full burden. It discloses the async/handoff behavior clearly ('root job finishing does NOT mean the run finished'), the extra Core call cost of include_chain, the default value of include_chain (false, back-compat), and the Core enforcement on per-job reads. It doesn't describe failure modes or rate limits, but for a status-polling tool the disclosed behavior is substantial.

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 moderately sized but dense with useful information. It front-loads the most important guidance (poll the WHOLE run, not just root job) in the first sentence, then follows with mode-specific usage and the include_chain behavior. A few phrases like 'THE EXECUTION'S IDENTITY' in the schema are slightly verbose, but the description itself is well-organized.

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 6 parameters, 100% schema coverage, no output schema, and a polling context, the description covers the essential behavioral choices well: chain vs job polling, include_chain cost, actor requirements. It lacks a few details like pagination (if any) and error/status value ranges, but the absence of an output schema means the description isn't expected to fully enumerate response fields. The complexity of the async chain model is adequately handled.

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 6 parameters, giving a baseline of 3. The description adds value by explaining the execution model: chain = root job + handoffs + askAnySkill subcalls, why actor_id is usually unnecessary but needed for different-actor jobs, and what include_chain's response contains. This context goes beyond the schema's one-line descriptions.

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

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

The description clearly identifies this as a polling tool for async test progress. It explicitly distinguishes two polling modes (chain_id for whole run vs job_id for one job), and the sibling list confirms it's distinct from ateam_chain_status/ateam_get_chain by focusing on test status polling. The verb 'Poll' plus specific resources (chain_id/job_id) makes the tool's purpose unambiguous.

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

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

The description provides explicit guidance on when to use each parameter: chain_id for the whole run with an explicit warning that root job completion doesn't mean run completion, job_id for single-job polling with detailed semantics, and include_chain when dispatching askAnySkill subcalls to avoid polling child job_ids separately. It also warns that actor_id is usually unnecessary since the session remembers the actor.

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 safety burden and discharges it thoroughly: it discloses restart behavior, merge semantics, the 'Refuses if no GitHub base exists (no silent nuke)' safety guard, the destructive 'Wipes connector dir' effect of replace:true, the unchanged-source no-op in force, and even explains the two pre-fix bugs it was designed around. Nothing about side effects is left for the agent to discover at runtime.

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 section earns its place: front-loaded purpose, then merge semantics, then compact bulleted modes with bolded option labels, then practical base64 guidance, then a short traps section. The structure makes the length navigable; only the historical bug narratives could arguably be trimmed, but they serve as behavioral documentation.

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 high-complexity tool with 7 params, 4 modes, a destructive option, and zero annotations, the description is remarkably complete: it covers merge behavior, refusal safety, wipe behavior, recovery via force, base64 escaping, and ref defaulting. The only minor gaps are that no output/response shape is described (no output schema exists to carry that burden) and no permission/auth prerequisites are mentioned.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value on top of the schema by explaining compositional semantics the per-parameter descriptions don't convey: how github:true and files:[] interact (base + overlay), the force/recovery scenario tied to stale shared secrets, and the recommendation to prefer content_base64 for multi-file connectors. This cross-parameter guidance exceeds what the individual property descriptions provide.

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 opening sentence 'Upload connector code to Core and restart — WITHOUT redeploying skills' names a specific verb, resource, and the key scope exclusion that distinguishes it from sibling redeploy/sync tools. The clarifying contrast ('WITHOUT redeploying skills') immediately tells an agent this is not ateam_redeploy or a GitHub write tool.

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 four enumerated modes spell out exactly which parameter combinations to use for which outcome (github-only, github+overlay, merge, full replace). It explicitly names the anti-pattern alternative ('do NOT hand-roll curl against the raw endpoint') and declares itself the 'CANONICAL agent path', giving the agent a clear decision rule that also routes around sibling GitHub 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 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.

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 does this thoroughly: it explains the postMessage data-fetching mechanism, states it runs in headless Chromium on the real host surface, records MCP tool calls, and explicitly discloses the fail-closed behavior on browser-mcp outage.

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 earns its place: it establishes the tool's purpose, explains the failure mode it prevents, describes the execution mechanism, lists the return shape, names the verdict distinctions, and states the fail-closed policy. The key purpose is front-loaded.

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

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

There is no output schema, so the description correctly takes responsibility for explaining the return value ({ ok, verdict, visible_text, calls, failures }). It also covers failure modes, timing, and authentication, making the definition complete for an agent deciding whether and how to invoke this 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 has 100% description coverage for all four parameters, so the baseline is 3. The description does not add parameter-specific meaning beyond the schema, but it does add helpful context about the plugin's MCP calls that relates to the 'expect.tools' assertion.

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 names a specific verb ('PROVE') and resource ('connector ui_plugin actually renders WITH DATA'), and frames it as the required evidence that a UI fix is complete. It also distinguishes its unique outcome categories ('invented tool name' / 'right tool, no data' / 'plugin never asked'), which clearly separates it from generic verify tools.

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

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

The description gives explicit timing guidance ('Run AFTER a UI/data fix'), tells the agent to quote visible_text in its report, and notes that authentication is required. It does not explicitly name alternative tools or state when not to use it, but the context is strong enough to route an agent appropriately.

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