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

With no annotations provided, the description carries full responsibility for disclosing behavioral traits. It does mention the confirm requirement for delete actions and suggests an availability check, but it fails to disclose other important behaviors: it does not state that migrate or update are also mutations, does not describe error/return formats, auth requirements, rate limits, or side effects on related resources. This is insufficient for a multi-action mutating 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 compact and structured: it opens with a broad context sentence, then narrows to the tool's scope, lists actions, and ends with two critical usage constraints. Every sentence contributes essential information without redundancy, though the action list is unavoidably long.

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 (17 parameters, 14 actions, nested objects, no output schema) the description is inadequate for an agent to correctly invoke most actions. It does not explain which parameters are required per action, what constitutes a valid 'availability' result, or what happens after a successful create/migrate/delete. The description would need to map actions to their supporting parameters to be 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 94%, so the schema already documents most parameters in detail. The description adds minimal value by listing actions and noting the confirm requirement, which ties to a parameter. It does not clarify which parameters apply to which actions (e.g., that 'create' needs tableDefinition, 'query' needs query), but the high schema coverage earns a baseline 3.

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

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

The description clearly states the tool's purpose: 'Manage Agent Tables within a project' and enumerates 14 distinct actions. This gives a specific verb-resource pair and is distinct from sibling debug_* and platform_* tools by its focus on agent tables. However, it does not explicitly contrast with any sibling tool, which keeps it slightly below a perfect score.

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 two concrete usage rules: 'Use availability first to diagnose TABLE_UNAVAILABLE' and 'Delete actions require confirm=true'. These are actionable guidelines. However, it does not specify when to prefer this tool over alternatives (e.g., platform_projects for project-level ops) or when not to use it, leaving a gap in routing 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 provided, so the description carries the full behavioral burden. It discloses what the tool returns (a list of diagnostic categories) and its automatic nature, but it does not explicitly state whether the operation is read-only, safe, or has any side effects. For a diagnostic tool this is likely assumed safe, yet the lack of explicit disclosure limits 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 reasonably concise: a purpose statement, a bulleted list of outputs, and a usage note. The opening line 'Arch explains documentation, diagnostics, and system health signals' is somewhat vague and could be trimmed, but it does not significantly inflate 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?

With just one optional parameter and no output schema, the description sufficiently explains the tool's role and output categories. It omits error handling or edge cases (e.g., invalid session ID), but for a diagnostic utility the provided information is adequate for an agent to call 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%: the single parameter sessionId is already well-documented with 'Session ID to analyze (uses active session if not specified)'. The tool description adds no further parameter guidance, 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's function: 'Get automated analysis and diagnostics for a session' and enumerates the categories of output (summary statistics, current state, detected issues, suggestions). This makes its purpose unmistakable and differentiates it from more specific sibling tools like debug_get_current_state or debug_get_errors, which focus on isolated aspects.

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

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

The description explicitly advises 'Use this as a starting point for debugging - it identifies common issues automatically,' which tells the agent when to invoke it as an initial diagnostic step. It does not, however, name alternative sibling tools or describe scenarios where this tool would be inappropriate, leaving some room for inference.

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 of behavioral disclosure. It discloses the return structure (config, findings, suggestions) and the configOnly behavior, but does not state whether the operation is read-only, has side effects, requires special permissions, or how it handles errors. As a diagnostic tool, this lack of clarity is a notable gap.

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 structured with a brief intro, then the core purpose, then parameter-specific usage. It is front-loaded with the main action and target. The first sentence about Arch is somewhat broad but not wasteful. Overall, it is concise enough and well-organized for the number of modes it covers.

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 must explain what to expect, which it does at a high level ('Returns config, findings, and suggestions'). It also covers the two diagnostic targets and the configOnly shortcut. However, it does not explain the impact of the 'depth' parameter or what constitutes 'findings' and 'suggestions', leaving some ambiguity for an agent that needs to interpret results 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 value beyond the schema by explaining the complementary use of sessionId vs agentName ('Provide sessionId for session diagnostics or agentName for agent config diagnostics') and the purpose of configOnly ('inspect only config... without running full diagnostics'). This adds meaningful guidance beyond the individual property descriptions.

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

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

The description clearly states the action ('Run diagnostic analysis') and the resource ('an agent or session'), distinguishing between session and agent config diagnostics. It also mentions the return content ('config, findings, and suggestions'). However, it does not explicitly differentiate from several sibling diagnostic tools (e.g., debug_analyze_session, debug_get_current_state), so it falls short of a 5.

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 clear context on when to use: 'Provide sessionId for session diagnostics or agentName for agent config diagnostics.' It also gives a specific alternative mode via configOnly, referencing the old debug_inspect behavior. However, it doesn't explicitly state when NOT to use this tool relative to the many sibling diagnostics, 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 must disclose behavioral traits itself. It indicates the tool returns diagnoses but does not mention whether it is read-only, whether it can modify files (the 'drives repair loops' phrase hints at mutation but is ambiguous), or any prerequisites like file access. This is a moderate description, lacking deeper behavioral 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?

The description is two sentences, but the first sentence is not tool-specific and reads as a generic system description. The core functional statement is in the second sentence, which is reasonably concise. The opening wastes space on peripheral context, reducing overall clarity and front-loading effectiveness.

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 5 optional parameters, nested objects, and no output schema, the description is minimal but not severely lacking. It explains the input (transcript + files) and output (diagnoses) at a high level. However, it does not describe the output format or how the input parameters interplay (e.g., path vs files vs data precedence), which an agent might need to call correctly. The schema covers parameter meaning, but the overall usage context is thin.

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 parameters are already documented in the schema. The description adds minimal value by mentioning 'transcript JSON plus project files,' which maps to the transcript and files/path parameters but does not clarify the distinction between path vs files vs data. It does not go beyond the schema's own descriptions, consistent with the baseline.

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

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

The description clearly states the tool's function: 'Given transcript JSON plus project files, returns correlated ABL file/line diagnoses.' It mentions it's an alias for debug_why_transcript_failed, which helps identify it among siblings. However, the lead-in 'Arch validates packages, inspects compiler-visible models, and drives repair loops' is vague and not directly specific to this tool, slightly muddying the 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 no explicit guidance on when to use this tool versus alternatives. It only mentions the alias, implying equivalence with debug_why_transcript_failed, but does not state when to choose this over other debug_* siblings like debug_diagnose or debug_explain_decision. No exclusions or clear use-case context is given.

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 behavioral burden. It mentions the platform_connect prerequisite, which is useful, but it doesn't disclose return format, whether topic and query are mutually exclusive (if both provided, which wins?), error behavior, or whether read-only. '[Arch Analyze]' is an unexplained label. For a read-style tool with zero annotation coverage, more behavioral disclosure is expected.

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 short and front-loads the main purpose. The usage modes are stated compactly in a single sentence. Minor waste: the '[Arch Analyze]' prefix adds no information to an agent and could be omitted. Overall efficient.

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

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

For a 2-parameter, 0-required tool with no output schema, the description covers the main usage modes well. However, the ambiguous interplay between topic and query, plus no mention of return structure or the meaning of '[Arch Analyze]', leaves an agent uncertain in edge cases. It's adequate but not rich.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds some value by explaining the three usage modes (topic/query/neither). However, it introduces ambiguity — the topic schema says 'Use without arguments to list all available topics' which is confusing (topic without arguments? both empty?) — and does not clarify whether topic and query can be combined or are mutually exclusive. The description adds marginal value but leaves an important interaction undefined.

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 or searches Agent ABL documentation, listing distinct modes (topic, query, or list-all). The verb 'explains documentation... Get or search' is specific about the resource. However, the leading '[Arch Analyze]' prefix is confusing — it seems like a tool-label not tied to the tool's function, and the description doesn't explicitly distinguish itself from the many sibling tools that also touch ABL documentation (e.g., debug_lint_abl, debug_arch_sop), so sibling differentiation is weak.

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

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

The description gives clear usage modes: provide 'topic' for full content, 'query' to search, or neither to list all topics. It also states a prerequisite — 'Requires platform_connect first' — which is valuable routing information against siblings. It does not explicitly state when not to use this tool vs alternatives, but the usage modes are quite explicit.

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 not mention whether the operation is read-only, any side effects, permission requirements, rate limits, or what the response contains. The generic opening about Arch connecting to live sessions offers no specific behavioral insight about this 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 concise at three sentences. It front-loads a general Arch context, then states the tool's specific purpose, and finishes with a value statement. The first sentence is generic across debug tools and could be trimmed, but overall the length is appropriate and readable.

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 5 parameters and no output schema, the description fails to explain what the tool returns, how the parameters relate to each other (e.g., turn vs. eventId), or any prerequisites like an active session. The meaning of 'decision event' is not defined, and there is no guidance on expected output structure, making the tool difficult 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%, with all five parameters documented in the input schema. The description adds no additional parameter semantics, but the baseline score of 3 is appropriate since the schema already explains each parameter's purpose adequately.

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

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

The description clearly states the action ('Get detailed explanation') and the resource ('a decision event') and even explains the underlying goal ('Helps understand why the agent made a choice'). While it doesn't explicitly contrast with sibling debug tools, the purpose is specific enough to differentiate from general tracing or state inspection 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?

There is no explicit guidance on when to use this tool versus alternatives like debug_get_flow_graph or debug_diagnose. The description implies it is for explaining decision events, but it lacks any exclusions or references to sibling tools that might handle similar cases. This leaves the agent without direction on tool selection.

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

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

No annotations are provided, so the description carries the full burden. It mentions that Arch connects to live sessions and inspects execution state, which gives some context, but it does not state whether the operation is read-only, requires permissions, or has side effects. It also leaves 'more' vague, leaving the agent uncertain about the full scope of the state returned.

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 one sentence and gets to the point quickly after a generic intro about Arch. It is concise, though the intro '[Arch Debug] Arch connects...' likely repeats across sibling tools and could be trimmed, but the core purpose is front-loaded and clear.

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

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

With no output schema, the description should clarify what state data is returned. It lists 'context, gather progress, flow state, and more', which gives a partial picture but omits the exact structure or any caveats. For a simple tool with one optional parameter, this is adequate but not comprehensive.

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 single parameter sessionId is fully described in the schema ('Session ID (uses active session if not specified)'), so schema coverage is 100%. The tool description adds no additional meaning about the parameter, which is acceptable given the baseline for full coverage.

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

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

The description clearly identifies the action ('Get') and the resource ('current agent state'), and lists specific components such as context, gather progress, and flow state. It is distinct from siblings in that it focuses on overall state, but it does not explicitly name alternative tools to differentiate from.

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?

There is no guidance on when to use this tool versus other debug tools like debug_get_span_tree or debug_get_errors. The description implies it is for current state, but it does not specify scenarios, prerequisites, or when to choose 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It conveys a read-only operation and names the content classes returned, but it does not disclose what happens when no active session exists, the return structure/format, or behavior when a session has zero errors. For an introspection tool with zero annotation coverage, this is a meaningful gap.

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 instruction portion is a tight single sentence with no wasted words, and the content specification is front-loaded. The opening '[Arch Debug] Arch connects to live sessions...' sentence adds mild product context but is partly redundant with the tool's family and could be trimmed; this prevents a perfect score.

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

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

The tool is simple (2 optional params, no output schema), and the description lists what it returns (errors, warnings, escalations, constraint failures), which covers the content dimension. However, with no output schema present, the return structure/format is entirely undocumented, and the live-session precondition is implied rather than stated. Adequate but with clear gaps.

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% (both sessionId and includeWarnings are documented in the schema), so the baseline is 3. The description adds nothing beyond what the schema already states about the active-session fallback and warning inclusion. It doesn't compensate further, which is acceptable given full schema coverage.

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

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

The description states a clear verb+resource ('Get all errors and warnings from the session') and adds specificity with 'Includes escalations and constraint failures,' which meaningfully narrows what is returned. It distinguishes itself from siblings like debug_session_history and debug_traces by its error/warning focus, though it doesn't name those siblings explicitly.

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 no guidance on when to choose this tool over alternatives such as debug_traces, debug_analyze_session, or debug_harness_logs. The opening product-context sentence ('Arch connects to live sessions...') implies a live-session dependency but never states when this tool is appropriate or when it is not. No exclusions or alternative routing is provided.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions connecting to live sessions and returning JSON or Mermaid format, giving some insight into behavior. However, it does not disclose side effects (likely read-only), permissions, or any potential errors. The disclosure is adequate but not exhaustive for a debug tool that may interact with live sessions.

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 paragraph with multiple sentences, but the opening sentence about Arch is generic and not directly about this tool. The core purpose is introduced in the second sentence. It's reasonably concise, but not perfectly front-loaded—the key 'get the execution graph' could appear earlier. There's some redundancy with the '[Arch Debug]' prefix and the first sentence.

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 moderate complexity (3 optional params, output format choice) and lack of an output schema, the description clarifies what the graph shows and mentions output formats. It doesn't elaborate on the structure of the JSON or Mermaid output, nor does it address limitations or prerequisites (e.g., needing an active session). While not completely detailed, it provides enough for an agent to understand the tool's purpose and basic usage.

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

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

Schema description coverage is 100%, so each parameter already has a description. The tool description adds limited extra meaning—it mentions agent types and output formats, but these are already covered by the schema enum for format and the descriptions for sessionId and includeAppGraph. Baseline of 3 is appropriate since the schema does the heavy lifting and the description adds marginal 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 verb 'Get' and the resource 'execution graph', and specifies the scope ('any agent type') and content ('flow steps, tools, handoffs, and routing logic'). It distinguishes itself from siblings like debug_get_current_state or debug_get_span_tree by focusing on graph structure rather than state or spans, though it doesn't explicitly name alternatives.

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 general context about Arch's debugging capabilities (connecting to live sessions, tracing failures, inspecting execution state) but does not explicitly state when to use this tool over its many debug siblings. Usage is implied by the description of the graph content, but there's no direct guidance on choosing between debug_get_flow_graph and debug_get_span_tree, debug_explain_decision, etc.

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 for behavioral disclosure. It does not state whether the tool is read-only, requires authentication, has rate limits, or produces side effects. The description focuses on the output nature (span tree) but omits any operational caveats or error scenarios.

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

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

The description is concise, with three sentences. The first sentence provides broad Arch context, the second states the tool's action, and the third gives a general use case. It is front-loaded with the specific action clearly stated. Minor waste in the generic Arch context sentence, but overall efficient.

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

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

For a simple tool with only two optional parameters and no output schema, the description is adequate for basic invocation. However, it does not explain what constitutes a 'span tree' beyond 'execution flow', nor does it describe the return structure or any potential pitfalls. The lack of output schema places more burden on the description to clarify the result format, which it only partially does.

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%: both 'flat' and 'sessionId' have descriptive text in the schema. The tool description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate given the schema's completeness.

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: 'Get hierarchical span tree showing execution flow.' This clearly indicates the tool's purpose. It doesn't explicitly differentiate from similar siblings like debug_get_flow_graph, but the mention of 'span tree' provides enough specificity for basic distinction.

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 guidance on when to use this tool versus alternatives. The phrase 'Useful for understanding agent behavior' is a vague benefit, not a usage condition or exclusions. No sibling alternatives are mentioned, leaving the agent to infer suitability from the generic 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 and handles it well: it discloses the HARNESS_API_KEY environment-variable prerequisite and states the return form ('parsed, readable log lines'). For a read-only log tool this is solid disclosure; finer details like empty-result or error behavior are omitted but not critical.

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?

Purpose is front-loaded and the structure is logical: purpose, usage context, common examples, filter guidance, auth requirement. Each section earns its place, though the '[Arch Evaluate]' platform preface adds some noise and the examples are slightly repetitive against the parameter names.

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 7-parameter tool with 100% schema coverage, no output schema, and no annotations, the description is reasonably complete: it covers the key scenarios, filter behavior, and the auth prerequisite. It could go further on edge cases, but the moderate complexity and full schema coverage keep this at a strong 4.

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 genuine value beyond the schema by tying parameters to real usage ('stage_id="build_test", step_id="unit_tests"' for test failures) and giving a concrete filter regex example ('ECONNREFUSED|mongo|redis'). This exceeds the baseline.

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

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

States a specific operation (download and parse) on a specific resource (Harness CI execution logs) and clearly distinguishes its purpose from siblings: it's the only tool among debug_* and platform_* siblings focused on retrieving CI logs. The phrase 'get full build/test failure logs beyond what an eval-run status summary includes' sharpens the 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?

Explains when to use it ('beyond what an eval-run status summary includes') and provides three concrete named scenarios mapping stage_id/step_id values to real failure types (test failures, Docker build errors, security scans). It doesn't explicitly name sibling alternatives or exclusions, so it falls just 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 provided, the description carries full responsibility for disclosing behavior. It mentions that Arch 'drives repair loops', but it is unclear whether this tool actually modifies files or triggers repairs, or if it is purely diagnostic. No side effects, permissions, or read-only guarantees are stated. The description should clarify whether this is a read-only check or if it can alter state.

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, but the first sentence ('Arch validates packages, inspects compiler-visible models, and drives repair loops') is tangential and not directly about this tool's purpose. The core action is in the second sentence, but the front-loading is wasted on context. It is concise overall, but the structure could be improved by leading with the tool's actual function.

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

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

The tool has no output schema and no annotations. The description does not explain what the tool returns (e.g., a report, errors, a pass/fail status), whether it requires a path or files, or any side effects. Given the tool's complexity (multiple lint categories), an agent would need more context to invoke it correctly and interpret 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?

The input schema already has full coverage (100%) for all three parameters (data, path, files), so the schema adequately describes their semantics. The description adds no further detail about how these parameters are used (e.g., whether path and files are mutually exclusive). Since coverage is high, the baseline is 3, and the description does not provide 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 states a specific verb and resource: 'Run ABL design and repair lint checks', which is clear. It enumerates what the checks cover (empty RESPOND values, finalize steps, undeclared variables, etc.), giving a concrete picture of the tool's function. However, it does not explicitly differentiate from sibling debug tools like debug_get_errors or debug_diagnose, leaving some ambiguity about when this specific lint tool is preferred.

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 guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical scenarios, or exclusions. The phrase 'Run ABL design and repair lint checks' implies a use case, but there is no explicit direction on when an agent should invoke it over other debug or validation tools.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does convey that this is a read-style listing operation returning active, subscribable sessions, which implies no destructive side effects. But it does not disclose the return format, whether sessions are returned with metadata, any ordering or limits, or pagination behavior. It adds some value but lacks rich behavioral 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?

The definition is efficient, with the core purpose front-loaded before the usage hint. The opening sentence '[Arch Debug] Arch connects to live sessions, traces failures, and inspects execution state' provides domain context but is arguably filler that could be trimmed. Overall it is tight and earns its 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?

For a zero-parameter listing tool with no output schema, the description covers the essentials: what it lists, where from (server), what property the items have (subscribable), and the primary use case (finding UI-created sessions). It doesn't describe the shape of a returned session, but given no output schema and no params, an agent has enough 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 tool takes zero parameters, so the baseline of 4 applies — there is no parameter documentation burden for the description to carry. Schema coverage is trivially 100% with an empty schema. The description correctly implies no inputs are needed to call the tool.

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+resource ('List all active sessions from the server') and adds meaningful scope ('that can be subscribed to' and 'created by the UI'). It distinguishes this from sibling session tools like debug_session_history and debug_analyze_session by emphasizing active/subscribable sessions from the UI. It stops short of explicitly naming a sibling it is not, which holds it back from a 5.

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 instruction 'Use this to find sessions created by the UI' gives a concrete usage condition, telling the agent when this tool is the right choice. However, it offers no exclusions and names no alternatives, despite several overlapping session siblings (debug_session, debug_session_history, debug_analyze_session) existing. The context is clear but the routing guidance is partial.

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 full responsibility for behavioral disclosure. It mentions that the tool returns agents grouped by domain, which is a behavioral detail, but it does not state whether the operation is read-only, whether it requires an active connection, or whether it has side effects. For a read-like listing tool, this is a significant gap.

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 core description is concise: 'List all available agents from the server. Returns agents grouped by domain.' However, the opening sentence '[Arch Debug] Arch connects to live sessions...' is a generic blurb that does not add tool-specific value and could be trimmed. Overall, it is efficient and front-loaded with the main action.

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

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

The tool is simple with one optional parameter and no output schema. The description tells what it does and the grouping behavior, but misses important context such as whether it is safe to call, whether it requires a connection, and what constitutes 'all available agents' (e.g., system vs user agents). Given the lack of annotations, this 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?

The schema already covers the single 'domain' parameter with 100% coverage and a description ('Filter by domain'). The tool description does not add any extra meaning about this parameter beyond what the schema provides. Given the full 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 clearly states the verb 'List' and the resource 'all available agents from the server', and adds that results are grouped by domain. It distinguishes from sibling tools like debug_list_active_sessions (sessions vs agents) and debug_get_current_state (state inspection). The purpose is unambiguous and specific.

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 guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or when it should be preferred over sibling tools like debug_list_active_sessions or debug_get_current_state. The context line about 'Arch connects to live sessions...' is general and does not help decision-making.

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 behavioral burden. It explicitly says "create a debug session," which indicates a side effect (state change). It also gives context that Arch "connects to live sessions, traces failures, and inspects execution state," which implies the tool is part of a broader diagnostic capability. However, it does not disclose whether the action is reversible, whether permissions are required, or what happens if the agent is already loaded. That's a moderate level of 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 three sentences: the first provides family context, the second states the action, and the third gives format guidance. Each sentence contributes, though the first sentence could be seen as filler about Arch overall rather than this tool specifically. Still, it's concise and the key action is front-loaded in the second sentence.

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 that loads an agent for debugging, the description explains the purpose, the agentPath format, and ties it to session creation. With no output schema and no annotations, it doesn't need to detail return values. It lacks explicit differentiation from sibling tools, but it's sufficiently complete for an agent to understand what it does and how to call 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?

Schema coverage is 100% — both agentPath and projectId are described in the schema. The description adds an example of the agentPath format, but this duplicates the schema's example. Since the schema already documents the parameters, the description adds marginal value beyond what's in the schema, so a 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 states a clear verb and resource: "Load an agent and create a debug session." It identifies the specific action (loading an agent) and distinguishes itself from sibling tools like debug_list_agents or debug_analyze_session by focusing on the loading step. The agentPath format example reinforces the exact resource being loaded.

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 tool is used as a first step in a debugging workflow by saying "Load an agent and create a debug session." However, it does not explicitly state when to use it versus alternatives, nor does it mention any prerequisites like requiring a projectId (though that is a required param). It gives the agentPath format guidance but no conditions for choosing this tool over debug_session or debug_analyze_session.

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

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

No annotations are provided, so the description carries full burden. It mentions 'possibly wait for the response' but doesn't disclose what happens if waitForResponse is false (does it return immediately? what does the response look like?), or whether it mutates state. It also doesn't describe the execution state inspection behavior referenced in the intro.

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 reasonably concise (two sentences) and front-loads the core action. The introductory phrase about Arch's capabilities adds context but is somewhat generic and could be trimmed. Still, it's efficient overall.

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 sends messages and optionally waits, it would benefit from explaining the response structure or return behavior, and how it fits in the debug workflow (e.g., after loading an agent). No output schema exists, so the description should clarify what the tool returns. It's adequate for a simple send action but lacks needed context for effective use.

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

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

Schema coverage is 100% (all four parameters—text, timeout, sessionId, waitForResponse—have descriptions). The description adds little beyond the schema: it mentions 'send message' and 'wait for response' but doesn't clarify how timeout relates to waitForResponse or what sessionId defaults to. Baseline 3 is appropriate because the schema covers 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 states a specific verb ('Send a message to the loaded agent') and the resource (the loaded agent). It also adds context about Arch's general purpose (connecting to live sessions, tracing failures, inspecting state). However, it doesn't explicitly differentiate from siblings like debug_session_history or debug_get_current_state—though the purpose is clear enough on its own.

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 debugging (sending messages to agents) but provides no explicit when-to-use vs alternatives guidance, no prerequisites (e.g., need to load an agent first via debug_load_agent), and no mention of when to use waitForResponse or timeout. It just states a generic action.

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. It reveals that subscribing provides 'buffered + live' traces, indicating the tool receives both historical and new events. It also clarifies the unsubscribe action. However, it does not mention side effects such as whether subscription persists across reconnects, the impact on other subscribers, or any permission requirements. It does not contradict anything, but it leaves room for more explicit disclosure of state changes and lifecycle behavior.

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

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

The description is concise (three sentences) and front-loads the purpose. The first sentence contextualizes the debug system ('Arch connects to live sessions...') which is slightly generic but still relevant. The core function, param usage, and a pointer to a sibling are all included with minimal waste. The structure flows logically from context to action to prerequisite lookup.

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 subscription-control tool with two required params and no output schema, the description is complete. It covers the action enum, the meaning of each action, and how to obtain the required sessionId. It does not describe the output format (the trace events themselves), but that is not expected for a subscription tool and would likely be covered by the event stream rather than a response. The pointer to debug_list_active_sessions closes the loop on parameter acquisition.

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 both parameters with descriptions, and the description adds value: it explains what 'subscribe' yields ('buffered + live') and points to debug_list_active_sessions for obtaining a valid sessionId. This goes beyond the bare schema by adding contextual meaning that helps the agent correctly construct calls.

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 core function: 'Subscribe to or unsubscribe from an existing session's trace events.' It identifies a specific verb (subscribe/unsubscribe) and resource (session trace events). It also distinguishes itself from debug_list_active_sessions by pointing to it as a source for session IDs, but does not explicitly differentiate from other debug tools like debug_get_current_state or debug_traces, which could be alternatives for inspecting state rather than subscribing.

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 guidance on the two actions ('subscribe' to start receiving traces, 'unsubscribe' to stop) and suggests using debug_list_active_sessions to find session IDs. However, it does not explicitly state when this tool should be used instead of alternative debug tools, nor does it mention any prerequisites (e.g., an active session must exist) beyond the sessionId source. The context implies it is for real-time trace subscription, but exclusions are not stated.

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 already declare read-only, idempotent, and non-destructive. The description adds critical behavioral detail: it performs one paginated request, does not retry, does not hydrate live stores, does not fall back, and treats Runtime as authoritative. This goes well beyond the structured 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 description is three sentences, compact and front-loaded with the core purpose. The opening bracket context is slightly generic but not wasteful, and every sentence serves a distinct role.

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 dual-action tool with many parameters, the description adequately covers both actions (list sessions and read trace events) and sets expectations about pagination and authoritative source. Without an output schema, it could mention return shape, but the schema and annotations compensate sufficiently.

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 description does not add parameter-specific meaning; it only frames the two actions (list and get). This meets baseline but provides no extra value for individual 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 explicitly states the tool lists durable historical Runtime sessions or reads a bounded page of persisted trace events, which maps directly to the two schema actions (list and get). It also contrasts with live session tools, making its resource and 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 specifies to use this tool when live debug buffers are unavailable or historical analysis is requested, which provides clear context. It does not explicitly name sibling alternatives or list when not to use it, but the guidance is direct and actionable.

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 states the core behavior (recent vs. filtered search) and gives a hint about the tool's broader role ('Arch connects to live sessions...'). However, it does not disclose details like pagination, sorting, or whether results are limited to the current session, which would be useful for an agent.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. It avoids superfluous details and lists filters efficiently. The only minor waste is the initial '[Arch Debug]' prefix, which adds little value, but the overall structure is clear and compact.

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

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

Given no output schema and no annotations, the description covers the fundamental usage (recent vs. search) and lists all filterable fields. However, it does not explain the interaction between filters (e.g., whether sessionId narrows a search or acts only as a filter) or the output structure. For a tool with six optional parameters, this is adequate but leaves some ambiguity for an agent.

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

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

Schema coverage is 100%, so each parameter already has a description. The description adds a key semantic distinction: the presence/absence of text, agentName, or hasError changes the operation mode. It does not go beyond this, but since the schema handles individual parameter definitions, a 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 clearly states the action ('Get and search trace events') and the resource ('trace events'), and lists the available filters (type, agent, text, error, session). It is specific enough to distinguish it from generic debug tools, though it does not explicitly name a sibling to contrast with.

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 conditional usage: with no search filters it returns recent events, with filters it searches stored events. This gives some context for when to apply each mode, but it does not mention when to prefer alternative tools like debug_get_errors or debug_session_history, nor does it state 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?

No annotations are provided, so the description carries the full burden. It mentions 'drives repair loops' but this seems to refer to the broader Arch system, not necessarily this tool. It does not disclose whether the operation is read-only or has side effects, nor what the tool actually returns. The example diagnosis format is fragmentary and ends with an unmatched quote.

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 long, run-on sentence that mixes a system-level preamble with a tool-specific explanation. The '[Arch Optimize]' tag and first clause are tangential and could be trimmed. The ending is malformed with a stray colon and quote, suggesting truncation. The core function is buried in the second half.

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

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

With five parameters, multiple input alternatives, and no output schema, the description should explain what the tool returns and its behavioral promise. It fails to mention the output format or any side effects. The example diagnosis is cryptic and incomplete. An agent would be left uncertain about the result and side effects.

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 five parameters. The description adds minor value by clarifying that the package can be supplied as a path or files map and the transcript as an object or path, but this is largely inferable from the schema. No additional semantic depth is provided.

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 eventually states a specific verb+resource: 'correlate transcript failure symptoms with ABL file/line diagnoses'. This is concrete enough to infer the tool's core function. However, it opens with a confusing preamble about 'Arch validates packages...' that does not directly describe this tool and could mislead. It does not explicitly differentiate from siblings like debug_diagnose_transcript.

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

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

No explicit when-to-use or when-not-to-use guidance is given. It lists input preconditions ('Given a transcript JSON and exported package...') but does not contextualize this against alternatives. An agent would have to guess when to call this over debug_diagnose_transcript or debug_diagnose.

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 lists actions and notes that compilation happens implicitly during version creation, but does not explicitly disclose side effects (e.g., save_dsl mutates state), permissions, or error behaviors. The mutation nature is only implied by 'update agent DSL'.

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 concise, front-loads the core purpose ('Manage agents within a project') and then lists actions. It includes a broad overview of Arch that is generic across platform_* tools, adding slight redundancy, but the structure is still efficient.

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

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

With no output schema, the description should explain return values for each action, but it only vaguely says 'get (agent details including DSL)' without specifying format. It also lacks error handling, pagination, or behavior on invalid input. The mention of implicit compilation is useful, but the overall completeness is insufficient for a tool with three actions.

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 75%, and the description adds meaning to the 'action' parameter by enumerating its values and linking them to required parameters (e.g., agentName for get/save_dsl). However, it does not elaborate on the other parameters beyond what the schema already provides, and the missing 25% (action) is partially compensated by the action list.

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 manages agents within a project and enumerates three specific actions (list, get, save_dsl), which distinguishes it from sibling tools like platform_projects or platform_versions. The verb 'Manage' is specific to the resource (agents).

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 the actions available (list, get, save_dsl) and the scope (within a project), but does not explicitly state when to use this tool vs alternatives or mention exclusions. It implies usage for agent management but lacks explicit routing 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 burden of disclosing behavioral traits. It mentions the actions (list, create, get, execute_action, record_decision) but gives no detail on their effects, side effects, required permissions, or what happens to data. The phrase 'project-scoped Auto Loop runs' adds some scoping context, but it does not explain the consequences of mutation actions like create or execute_action, which is a significant gap.

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 but includes a somewhat redundant opening ('[Arch Optimize] Arch validates...') that provides background context rather than tool-specific instructions. It is not overly long, but the first sentence could be trimmed without losing core information. The action list is useful but not explained. Overall, it is reasonably compact but could be more streamlined.

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

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

Given that the tool has five distinct actions with different operational requirements, the description is insufficiently detailed. It does not explain what each action does, when to use which, what parameters are relevant per action, or what the response looks like (no output schema). An agent would struggle to correctly invoke this tool without further clarification, especially for create and execute_action which likely require a body.

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 covers 75% of parameters with descriptions, and the description lists the actions (the main enumerated values) but does not add meaning beyond the schema. It does not explain what each action does, what body should contain, or how runId is used per action. Since coverage is close to high, the baseline is 3, and the description offers minimal additional 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: it drives Arch Auto Loop repair workflows through the Studio API. The opening line gives context about what Arch does (validates packages, inspects models, drives repair loops), and the list of actions specifies the available operations. It distinguishes itself from siblings by focusing solely on the Arch Auto Loop domain, which is unique among the listed platform_arch_* 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 implies usage for Arch Auto Loop repair workflows but does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or when-not-to-use conditions. The phrase 'Drive Arch Auto Loop repair workflows' provides a general context, but there is no comparative guidance against siblings like platform_arch_sop or platform_validate_package.

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 correctly discloses that the tool creates and changes projects, agents, tools, configuration, versions, and deployments (a mutating, state-changing tool). It does not contradict anything. But it omits behavioral details like response behavior, required sequence (e.g., creator → upload → message → project), or side effects of the body override. 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?

Four sentences with the action list front-loaded and the critical routing guidance up front. The [Arch Build] tag orients the reader, and the actionable mapping to actions is efficient. Slightly long on the enumerated action list, which partially repeats the schema enum, but overall well-organized and 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?

This is a complex compound tool with 8 actions and 12 parameters, and the description guides only 5 of the actions. No output schema exists, so return behavior is nowhere documented. Given the tool's complexity, the description covers the primary workflow well but leaves the auxiliary actions (get_session, continue, recover, cancel) and sequencing details unexplained, which is a notable 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?

Schema coverage is high at 92%, so the schema already documents most parameters and the baseline is 3. The description adds a modest mapping of text→send_message, file→upload_file, and fileRefs→send_message, which clarifies which params belong to which action. But this is largely redundant with the schema descriptions, so the added value is marginal.

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 clear purpose: driving Arch SOP-build sessions through the Studio API. Lists the 8 distinct actions with specific verbs (create_session, upload_file, send_message, create_project) and describes what Arch does overall. Explicitly differentiates the actions from one another, so an agent knows the tool is a polymorphic driver rather than a single-purpose call.

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

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

Provides explicit when-to-use routing for the core actions: create_session for SOP/onboarding or in-project sessions, upload_file for SOP/source files, send_message for SOP-build instructions/fileRefs, and create_project for materializing the project. This is actionable guidance. However, it leaves get_session, continue, recover, and cancel without usage context, and doesn't address how this tool relates to the many debug siblings.

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

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

With no annotations, the description carries the full burden. It discloses that raw secrets are not placed in MCP context and that secure secret entry/OAuth consent happens via the Studio flow. It also lists the action verbs, giving a hint of behavior. But it does not describe side effects, return values, or constraints like the confirm flag for destructive actions, which 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 dense paragraph, which is not ideal for scanning. It front-loads the Arch Build context and then lists actions, but the structure could be improved with bullet points or clearer separation of purpose vs. usage. It is not overly verbose, but not optimally 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 the tool's complexity (23 parameters, 10 actions) and lack of output schema or annotations, the description is incomplete. It does not explain the purpose of each action, when to use each, or what the responses look like. The secure flow is mentioned but not detailed enough for an agent to know exactly how to initiate or complete OAuth. Significant guidance 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 description coverage is only 35%, and the description compensates only marginally. It clarifies that `config` rejects raw credentials and that `connectionConfig` is for OAuth URL templates, but it does not explain most of the 23 parameters (e.g., name, tags, scope, usageMode, visibility, environment). With such low schema coverage, the description should cover more parameter semantics to be 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 clearly states the verb and resource: 'Manage project auth profiles'. It enumerates the supported actions and mentions the key constraint of not placing raw secrets in MCP context. However, it does not explicitly distinguish itself from sibling tools like platform_integrations or platform_projects, relying on the 'auth profiles' specificity to separate it.

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 tool is for managing auth profiles and mentions the secure Studio flow for secret entry, giving some context on when to use it. However, it does not explicitly state when not to use it or compare against alternatives among the many platform_* siblings. The guidance is implied rather than explicit.

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 lists actions and their short descriptions (e.g., update_settings modifies settings), but does not disclose side effects, whether updates are destructive or merge, permission requirements, or response behavior. The 'modify settings' is vague and does not explain impact.

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

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

The description is reasonably concise but front-loaded with a generic 'Arch Build' introduction that doesn't directly serve the tool's purpose. The actionable part is the 'Manage project configuration' and action list, which is fine. Could be trimmed to be more focused.

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 multi-action tool with no output schema and only minimal parameter descriptions, the description lacks essential context. It does not clarify what settings or LLM configuration contain, how updates apply, or what success/failure looks like. An agent would need additional information to invoke actions correctly, especially update_settings.

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 67%, with projectId and settings described. The description adds no additional parameter meaning beyond the schema; it merely repeats action names. The actions themselves are self-explanatory via enum, but settings structure remains unspecified. Baseline of 3 is appropriate given schema coverage, but description does not compensate.

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

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

The description states the tool manages project configuration and lists specific actions (get_settings, update_settings, get_llm_config, update_llm_config). It clearly identifies the resource and operation, and distinguishes it from sibling tools focused on projects, versions, deployments, etc. However, it includes an extraneous 'Arch Build' intro sentence that adds noise.

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?

There is no explicit guidance on when to use this tool versus alternatives. The description implies it's for configuration, but does not mention any exclusions or comparison to sibling tools like platform_projects or platform_versions. The agent must infer when configuration actions are 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?

Describes authentication flow in detail: stored credentials → device auth with automatic browser opening and polling, single call, no two-phase. Discloses credential storage, safe WebSocket replacement on new authToken, environment change restrictions, and successful response metadata. Since no annotations exist, description carries full burden and exceeds it.

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?

Though lengthy, every sentence adds critical context. Front-loads purpose and usage order, then covers auth, edge cases, and error handling without redundancy. Each clause 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?

Comprehensive for a connection tool with 6 params, no output schema, and no annotations. Covers prerequisites, authentication flow, failure handling, environment selection, and response metadata, leaving no critical gap for an agent to call 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 baseline is 3. Description adds valuable context beyond schema: authToken replacement behavior, serverUrl environment selection fallback, force requirement for environment changes, and deprecation guidance. This pushes above baseline but not to 5 since schema already covers core 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?

States a specific action: connect to the server WebSocket for Arch debugging. Clearly identifies it as the first step before other Arch debug tools, distinguishing it from siblings like debug_list_active_sessions or debug_traces.

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 'Call this first before using other Arch debug tools.' Provides conditions for force usage, environment change rejection, and tells the agent to ask the user for environment if not specified. Also forbids alternative approaches like REST calls.

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 mention that rollback/restore/retire require confirmation and that qualification bypass requires a reason and permission, which signals some state-changing behavior. However, it does not explicitly state that these operations modify live deployments, that create/promote are destructive, or that any operation might have side effects. It also omits details about return values or potential errors. The description provides partial transparency but leaves significant behavioral ambiguity for a tool with multiple mutating actions.

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 not excessively long but includes a broad opening sentence about Arch creating and changing projects, agents, tools, etc., which is tangential and adds noise. The core information about deployment management and constraints is present, but the structure could be tighter by leading with the deployment-specific purpose and moving the broad context elsewhere. It is readable but not optimally concise.

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—17 parameters, 7 actions, nested version manifests, and multiple workflows—the description is inadequate. It does not explain how different actions interact with parameters, what deploymentId is required for, what the difference is between force and bypassQualificationGate, or how to construct a valid request for each action. With no output schema, the description also fails to set expectations for return values. An agent would struggle to correctly invoke this tool without additional documentation or examples.

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

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

Schema description coverage is 65%, so the schema already provides descriptions for most parameters. The description adds some value by explaining that confirm is required for certain actions and that bypassQualificationGate needs a reason, which ties to bypassReason. However, it does not clarify the mapping of actions to specific parameters (e.g., create uses environment, promote uses targetEnvironment) or explain the semantics of nested version manifests beyond what the schema states. Overall, the description supplements but does not significantly enrich parameter understanding.

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 manages deployments, specifically with typed version manifests, and enumerates the supported actions: list, get, create, promote, rollback, restore, and retire. It distinguishes this tool from siblings like platform_versions and platform_workflows by focusing on deployments as the resource. However, it falls short of a 5 because it doesn't explicitly connect each action to its purpose or differentiate from closely related tools beyond the resource name.

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 some usage constraints: rollback/restore/retire require explicit confirmation, and qualification bypass requires a reason and existing server permission. This is helpful for deciding when to use those actions. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide conditions for when not to use it. The guidance is implicit from the tool name and domain, but not explicit comparison with sibling tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'Manage' and lists actions, revealing nothing about side effects, permissions, rate limits, reversibility, or the meaning of the confirm parameter (which is necessary for delete). The description adds no behavioral depth beyond what the schema already enumerates, making it inadequate for an agent to anticipate consequences.

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 short (two sentences), but the first sentence about Arch Evaluate is generic context not specific to this tool, adding noise. The key information (resource + endpoint + actions) is in the second sentence, which is front-loaded enough. It is concise but could be tighter by removing the introductory clause and focusing solely on evaluator management.

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, nested objects, and no output schema or annotations, the description is under-specified. It does not explain what each action returns, the meaning of 'templates', the requirement to set confirm=True for delete, or any error handling. An agent calling this tool for the first time would lack critical operational details, making the definition incomplete for correct invocation.

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

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

Schema coverage is 83%, so most parameters (action, projectId, evaluatorId, confirm, body, query) already have descriptions or enums. The description adds no additional parameter meaning—it merely repeats the action list already in the enum. Per the rubric, high schema coverage sets a baseline of 3, and the description does not enhance parameter understanding, so the score holds at 3.

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

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

The description clearly states the tool manages 'eval evaluators' and lists specific actions (list, get, create, update, delete, templates), making the resource and operations explicit. It is distinct from nearby eval siblings like personas, scenarios, sets, and runs, though it does not explicitly contrast itself with them. The leading Arch Evaluate context is slightly tangential but does not obscure the core 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 no guidance on when to use this tool versus alternatives. It does not mention which sibling tools to prefer, when to choose list vs get vs templates, or any conditions or exclusions. The actions are self-evident from the enum, but the description offers no contextual decision-making help, leaving the agent to infer usage.

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

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It only lists actions and mentions the API path, but does not disclose side effects (e.g., whether delete is permanent, whether create/update are idempotent, any authorization requirements, or what happens on failure). The description gives minimal behavioral context beyond the action names, which is inadequate for a mutation-heavy 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 paragraph that front-loads the high-level context ('[Arch Evaluate]...') before stating the tool's purpose and actions. It is concise with no redundant phrasing, though the introductory sentence about Arch generating eval assets is somewhat generic and could be trimmed. Overall, it is efficiently structured and wastes little space.

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 seven distinct actions and no output schema, the description is incomplete. It does not explain what each action returns, what 'templates' or 'generate' specifically do, or any behavioral nuances like required confirm for delete. With no output schema and minimal annotation coverage, the description should provide more operational detail to enable correct invocation, but it falls short.

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 descriptions for most parameters (83% coverage), including that 'body' is for create/update/generate, 'query' is optional for list, 'confirm' must be set for delete, and 'personaId' is for get/update/delete. The tool description adds little beyond the schema; it does not elaborate on parameter formats or valid values beyond what is already present. Since schema coverage is high, 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 clearly states the tool's purpose: 'Manage eval personas' and enumerates the supported actions (list, get, create, update, delete, templates, generate). The resource (personas) is specific and distinct from sibling tools like platform_eval_scenarios or platform_eval_runs, though it does not explicitly differentiate itself from them. The verb and resource are clear, so the purpose is unambiguous.

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

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

The description implies usage by stating it manages personas, but it provides no explicit guidance on when to choose this tool over the many sibling eval tools (scenarios, evaluators, sets, runs). There is no mention of alternatives or exclusions. The context is clear for personas, but the absence of any when-not-to-use or alternative routing leaves the guidance at the implied level.

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 disclosing side effects, prerequisites, or safety. It lists actions like create, update, cancel, start (mutations) but does not describe potential impacts, auth requirements, or reversibility. The generic statement about 'generates, runs, reads' does not cover operational behavior.

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

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

The description is two sentences, front-loaded with context, and the action list is compact. No fluff, but the long action list could be better structured (e.g., grouped by type). Still, it's concise and efficient.

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

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

For a multi-action tool with 12 actions, nested params, and no output schema, the description is incomplete. It doesn't explain what each action does, expected return values, or practical usage. An agent would need to infer behavior from action names and schema alone, which is risky for complex operations.

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 83% and each parameter already has meaningful descriptions (e.g., runIds: 'Exactly two run IDs for compare. Prefer this over query.runIds.'). The description only repeats the action enum without adding semantics. It barely adds value beyond the schema, so a 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 states the tool manages eval runs for ABL repair loops, which is a specific verb-resource pair. It also provides context about Arch generating eval assets and reading CI evidence. However, it doesn't explicitly differentiate from sibling tools like platform_eval_sets or platform_eval_scenarios, so it's clear but not strongly distinctive.

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 explicit guidance on when to use this tool versus alternatives. It only says 'manage eval runs' without indicating scenarios or exclusions. Given multiple eval-related siblings, the agent has no cues 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?

Annotations are absent, so the description carries the full burden of behavioral disclosure. It lists actions but does not explain effects of each (e.g., confirm flag for delete, whether generate is synchronous, data persistence, permissions, or side effects). The opening sentence about Arch's capabilities is general and does not address this tool's behavior.

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

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

The description is short and front-loaded with the API endpoint and actions, but the first sentence about Arch's general capabilities is tangential and may confuse the agent by implying broader scope. The second sentence is focused, but the overall structure lacks directness.

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

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

The tool has multiple actions and six parameters with nested objects, and there is no output schema. The description does not explain request/response formats, error handling, or the specific meaning of 'generate'. Given the complexity and lack of annotations, the description is insufficient for an agent to call the tool correctly without additional inference.

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 83%, so most parameters already have descriptions in the schema. The description adds no parameter-specific information beyond what the schema provides, and it does not clarify how 'body', 'query', or 'confirm' map to the actions. Baseline 3 is appropriate because schema handles most parameter meaning.

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 resource (eval scenarios) and the actions (list, get, create, update, delete, generate) and provides the API endpoint. It is specific enough to distinguish from sibling tools like platform_eval_personas or platform_eval_runs, though it does not explicitly name sibling exclusions.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, typical use cases, or situations where another tool should be chosen. The only hint is the resource name, which is implicit rather than explicit 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 full responsibility for behavioral disclosure. It states only the CRUD actions and endpoint, but says nothing about side effects, permissions, idempotency, or the requirement for 'confirm' on delete (only present in schema). This is insufficient for an agent to anticipate mutation consequences.

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 brief but includes an introductory sentence about Arch that is not directly relevant to this tool's selection, costing it value. The essential CRUD and endpoint info is present, but the extra context dilutes the focus. A tighter description would remove the general Arch statement.

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 CRUD tool with 6 parameters and no output schema, the description is incomplete. It does not mention response formats, pagination for list, error behaviors, or that delete requires confirm=true. The schema carries most of the burden, but the description fails to connect actions with parameter requirements, leaving gaps for an agent.

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

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

Schema description coverage is high (83%), so the baseline is 3. The description adds no additional parameter meaning beyond what the schema already provides. It does not explain how 'body', 'query', or 'setId' interact with specific actions, leaving the agent to rely entirely on the schema.

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

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

The description clearly states the resource (eval sets) and the specific operations (list, get, create, update, delete) via the provided endpoint. It distinguishes this tool from siblings like platform_eval_runs and platform_eval_evaluators by focusing on 'sets'. The action enum further clarifies the exact verbs available, making the purpose unambiguous.

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

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

The description implies usage for managing eval sets but does not explicitly compare with alternative tools. It lacks guidance on when to use this over platform_eval_runs or platform_eval_evaluators, and gives no exclusions. The opening sentence about Arch generating eval assets provides broad context but no specific decision framework.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly describes that import is destructive and requires confirmation, explains the preview and apply flow, and mentions the accepted input forms (data.files, files, path). It also names the export output (file map + manifest). This is strong coverage for a mutation tool, though it doesn't detail edge cases like rollback behavior or permission requirements.

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 dense paragraph with some redundancy (e.g., the opening sentence about Arch Build is not specific to this tool's core function). The key actions are listed but not front-loaded; the description could be restructured to put the import/export purpose and actions first. It is informative but not optimally concise.

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

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

Given 10 parameters, 4 actions, and nested objects, the description provides a solid high-level overview: it explains the action types, the preview/confirm flow, and the input methods. It does not cover every parameter, but since schema coverage is high and each parameter has descriptive comments, that load is carried by the schema. The description is complete enough for correct tool invocation.

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

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

Schema description coverage is 90%, so the schema already documents most parameters. The description adds valuable synthesis by grouping the three alternative input mechanisms (data.files, files, path) and clarifying that confirm is for destructive imports. This goes beyond the schema's individual parameter descriptions and helps the agent choose the right input format.

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

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

The description clearly states the tool is for importing and exporting projects, enumerates the four actions with brief one-line purposes, and distinguishes it from the broader Arch Build operations mentioned in the first sentence. An agent can immediately understand what this tool does and how it differs from siblings like platform_projects or platform_project_builder.

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

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

The description provides clear context that this tool handles project import/export and outlines the typical flow (export_preview then export, import_preview then import). However, it does not explicitly compare to sibling tools or state when NOT to use this tool versus alternatives like platform_projects for simple project management. The guidance is clear but 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It lists actions including delete and test, which imply mutability and potential destructive effects, but does not explicitly state consequences, permission requirements, or idempotency. The existence of a 'confirm' parameter hints at safeguards but is never explained.

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 first sentence '[Arch Build] Arch creates and changes projects, agents, tools, configuration, versions, and deployments.' is generic and not specific to this tool, adding noise and diluting focus. The second sentence is concise but the overall structure is not front-loaded with tool-specific 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?

Insufficient for a 10-parameter tool with no annotations, no output schema, and 0% schema coverage. The description does not explain the role of key parameters, the exact behavior of each action (e.g., what 'test' does), or any expected response. An agent cannot safely execute even the simplest operation without additional information.

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

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

Schema description coverage is 0%, and the description fails to explain any of the 10 parameters. It only mentions 'auth profile' conceptually but does not connect it to the authProfileId parameter. Agents cannot determine the meaning or required format of projectId, connectorName, displayName, status, confirm, metadata, etc., making correct invocation nearly impossible.

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

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

Clearly states it manages connector/integration connections that bind a connector to an auth profile, and enumerates specific actions (list, get, create, update, test, delete). This distinguishes it from siblings like platform_connect by focusing on the binding to an auth profile. The purpose is specific and actionable.

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 a specific prerequisite: 'Use platform_auth_profiles first when the connection requires authentication.' This is useful guidance. However, it does not explain when to use this tool versus other platform tools (e.g., platform_mcp_servers) or when to choose each action. The usage context is only partially implied by the action list.

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 disclosure burden. It mentions that authentication uses authProfileId and raw credentials are never accepted, which is useful, but it does not explain side effects of actions like 'delete' or 'disconnect', whether operations are reversible, or permission requirements. The action list names operations but without behavioral 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?

The description is of moderate length and does start with a clear purpose after an unnecessary '[Arch Build]' prefix. The action list is valuable and front-loaded. However, the opening sentence about Arch creates general context that distracts from the core purpose. It is structured but could be tighter.

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

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

With 23 parameters, 13 actions, and no output schema, the description is severely inadequate. It does not explain how parameters differ per action, what each action returns, or error conditions. Even basic context like the relationship between serverId and projectId is missing. This tool cannot be correctly used based on the description alone.

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 a mere 4%, so the description must compensate heavily. It only mentions authProfileId and the action parameter implicitly. None of the 23 parameters are described in the text, and the schema itself lacks descriptions except for authType. There is no mapping of which parameters apply to which actions. This is a critical gap for a tool with this parameter count.

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 this tool provisions MCP servers and turns discovered server tools into project tools, listing 13 distinct actions. The verb 'provision' and resource 'MCP servers' are specific. It differentiates from sibling tools like 'platform_tools' (managing project tools) and 'platform_connect' (connections) but does not explicitly name those alternatives, so it is not a full 5.

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 context on what the tool does but provides no guidance on when to use it versus sibling tools. It does not state exclusions, alternatives, or specific conditions for selection. An agent has to infer usage from the action list alone, which is insufficient for 13 actions.

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 disclose behavioral traits. It states what the tool shows but does not mention side effects, read-only status, required permissions, or whether it connects to a live system or works offline. This is a significant gap for a tool that inspects local packages, as agents need to know if calling it modifies state or requires setup.

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 but the first sentence focuses on Arch's broader behavior ('Arch validates packages, inspects compiler-visible models, and drives repair loops') rather than the tool's specific function. This adds some noise. The second sentence is clear and lists components, but the opening could be trimmed to be more direct 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 enumerates what the tool returns (list of components) but lacks details on output format, return value structure, or any behavioral caveats (e.g., what happens with invalid paths). With no output schema and no annotations, this is a moderate gap. However, the list of components provides a reasonable understanding of the tool's scope.

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 each parameter (data, path, files) has a description. The tool description itself does not add parameter-specific guidance beyond what the schema provides. Baseline of 3 is appropriate since the schema does the heavy lifting and the description does not contradict or confuse parameter usage.

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 what the platform compiler sees in a local project package' and enumerates the specific components (agents, tools, handoffs, memory variables, behavior profile references, flow steps, unresolved refs). This distinguishes it from siblings like platform_validate_package (validation) or platform_project_builder (build), making the purpose unambiguous.

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

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

The description implies use for inspection of a package's compiler-visible model but does not explicitly state when to use it over alternatives or when not to use it. The first sentence mentions Arch validates packages, inspects models, and drives repair loops, which hints at context but lacks clear directives such as 'use this instead of X' or prerequisites. Sibling names suggest differentiation, but no exclusions are given.

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 contradiction with annotations: 'creates and changes' aligns with readOnlyHint=false and destructiveHint=false. The description adds some context beyond the annotations—the registry/envelope abstraction and the 'authoritative live' readiness inspection—but stays abstract and does not disclose specifics like reversibility, effect scope, or what 'changes' entails.

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, fairly compact, with the primary 'creates and changes' behavior front-loaded. However, phrasing is jargon-dense ('domain-neutral project-building contract', 'authoritative live project dependencies/readiness'), which hurts readability without adding much clarity for a fixed word budget.

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 three-branch oneOf builder with an output schema, the description conveys the abstraction model and provider extension plan, but remains vague about the actual change semantics and doesn't map the branches to agent decisions. A complex multi-action tool warrants more concrete guidance than this provides.

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 oneOf branches and action consts carry the parameter semantics. The description adds value by mapping natural-language actions (describe/inspect/plan) to the schema's action values, but provides no syntax or format detail beyond the headroom the schema already gives.

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 the core verbs—'creates and changes projects, agents, tools, configuration, versions, and deployments'—and lists the specific sub-actions (describe, inspect, plan) that match the schema's action consts. However, it is abstract ('domain-neutral project-building contract') and does not differentiate from siblings like platform_project_builder_operations or platform_projects, so the agent gets the resource but not the distinguishing boundary.

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

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

No explicit when-to-use vs when-not-to guidance. The only usage-ish signal is 'Workflow is the first provider,' which hints at provider context but offers no exclusions or comparisons to the many platform_* siblings. The three action branches are implied rather than tied to 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?

Annotations already declare destructiveHint=true, and the description adds the action list (cancel, execute) which implies destructive capabilities. It also mentions 'attempt-bound governed actions' but doesn't describe consequences, async behavior, or state mutation details. This adds some context beyond annotations 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?

Two concise sentences front-load the purpose and enumerate actions without fluff. The description is efficient, though it could be trimmed by omitting redundant phrases like 'Authoritative Studio state' if not actionable.

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 an output schema and detailed input schema, the description lacks operational context: it doesn't explain when to use 'dependency_report' vs 'readiness_report', what each action entails, or how the 'domain' parameter factors in. For an 8-action tool, this is a significant gap that could cause incorrect usage.

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

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

Schema coverage is 100% and the oneOf structure clearly defines all actions and required fields. The description adds no additional meaning to parameters like projectId or operationId; it only maps action names to their general purpose. With the schema carrying the full semantic load, 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 clearly states the tool manages operations for building projects, listing actions like list, read, resume, cancel, and execute. It names the core resource (projects) and distinguishes the operation lifecycle from the build itself, though it doesn't explicitly contrast with the sibling 'platform_project_builder' 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?

No explicit when-to-use or when-not-to-use guidance is provided. The description mentions 'registered domain provider' and 'authoritative Studio state' but never explains how to choose this tool alongside siblings like 'platform_project_builder' or 'platform_arch_sop'. An agent must infer usage context from the action list alone.

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 of behavioral disclosure. It does not mention that delete is a destructive operation requiring confirmation (the confirm parameter exists in the schema but is not referenced in the description), nor does it describe side effects, permissions, or return formats. The description is purely operational, leaving an agent unaware of safety implications beyond what the schema hints at.

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 paragraph but includes a broad, generic opening line ('Arch creates and changes projects, agents, tools, configuration, versions, and deployments.') that is not directly relevant to managing projects and wastes tokens. The action list is functional but could be formatted more clearly (e.g., bullet points). It is adequately sized but not front-loaded optimally; the core purpose statement comes after the generic preamble.

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 (5 actions, 6 parameters, no output schema), the description covers the action set and parameter usage but omits important operational details: what list returns (e.g., pagination), what get returns, error handling, or the need to set confirm=true for delete (which is only in the schema). The description is adequate for a simple CRUD tool but leaves gaps that could affect correct invocation.

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

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

Schema description coverage is 83%, which is high, so the schema already documents most parameters. The description adds value by mapping parameters to actions (e.g., 'name required for create', 'projectId required for get/delete/update', 'entryAgentName only for update'). This contextual pairing helps an agent know which parameters to fill for which action. The description also mentions that entryAgentName can be set to null to clear, reinforcing schema details. This exceeds the baseline of 3.

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

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

The description clearly states 'Manage projects on the platform' and enumerates the actions (list, get, create, update, delete). This distinguishes it from siblings focused on other resources. However, the opening sentence about Arch creating agents, tools, configurations, etc., broadens scope unnecessarily and could confuse an agent about the tool's exact resource boundary. Still, the core purpose is specific and clear enough.

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 guidance on when to use this tool versus alternatives like platform_project_builder or platform_project_builder_operations. It only lists actions and parameters without any context such as 'use this for basic CRUD' or 'for complex builds, use platform_project_builder.' No exclusions or routing cues are present.

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 behavioral disclosure burden. It does reveal a key trait: create_key returns the raw public key only once. It also explains create_channel's binding behavior. However, it omits details like whether create operations are idempotent, any required order (e.g., key before channel), or consequences of mutation. It provides partial transparency but not comprehensive.

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

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

The description is fairly succinct, with a front-loaded scope statement followed by a compact action list with necessary clarifications. The opening '[Arch Build]' and general 'Arch creates and changes...' sentence could be trimmed, but the core information is presented efficiently 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?

For a tool with 11 parameters, 4 actions, nested objects, and no output schema, the description is incomplete. It does not describe return formats, how actions interrelate (e.g., that create_key yields a publicApiKeyId used by create_channel), or handling of nested parameters like permissions. Agents would need to infer much of the behavior from parameter names and enums, leaving significant gaps.

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 64%, so the description adds some value beyond the schema. For create_channel it clarifies that channelType and environment are tied to binding a key to a deployment, which helps interpret parameters like publicApiKeyId. However, it does not elaborate on permissions, allowedOrigins, offset, or limit, leaving gaps that the schema only partially fills. Moderate supplementation.

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's focus: 'Manage the public SDK bootstrap surface' and enumerates four specific actions (list_keys, create_key, list_channels, create_channel) with brief semantic notes (e.g., 'raw public key returned once'). This distinguishes it from sibling tools that manage other platform resources, though the opening line about Arch broadly is generic and could be trimmed.

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

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

No explicit guidance on when to use this tool versus alternatives. It states the scope ('SDK bootstrap surface') but does not mention exclusions, prerequisites, or name any sibling tools for comparison. Given many platform_* siblings, agents must infer when to pick this one based on the action list alone.

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 pagination behavior (use page and limit), destructive delete behavior (force and confirm, 409 error without force), and test timeout. However, it does not describe the return format, success/error structure beyond the one 409 case, or side effects of create/update operations. The 'Note: tool CRUD routes through the Studio API' adds minor context but is not deeply behavioral.

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 structured with an action list and relevant parameter usage, but it opens with a broad, misleading sentence about managing projects, agents, tools, etc., which is unnecessary and could confuse. The core content is efficient, but the opening wastes words and detracts from the tool's actual purpose, making it less concise than it could be.

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 12 parameters and 6 actions, the description covers key actions and important operational details like pagination, force delete, and test timeout. However, it omits expected return values (no output schema exists), error handling beyond the 409 case, and specifics about the 'definition' object structure for create/update. These gaps leave the agent partially uninformed about full usage requirements.

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

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

Schema coverage is high (92%), so baseline is 3. The description adds practical meaning beyond the schema: it explains page/limit usage for pagination, force/confirm for delete, and timeoutMs for test. These clarifications help the agent understand how to properly use the parameters, going beyond the schema's basic property 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 the tool as managing tools within a project, listing six specific actions (list, get, create, update, delete, test). It distinguishes from siblings like platform_projects and platform_agents by focusing on the 'tool' resource. However, the opening sentence unnecessarily broadens scope to projects, agents, configurations, etc., which creates slight ambiguity about whether this tool handles all those entities or just 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?

No explicit guidance is provided on when to use this tool instead of sibling tools like platform_projects or platform_agents. The description implies tool-specific management but the first sentence muddies this by claiming it 'creates and changes projects, agents, tools...' without clarifying that this tool is only for tools. There are no exclusions or alternatives mentioned, leaving the agent to infer the appropriate context.

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

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

No annotations are provided, so the description carries the full burden. It discloses that it returns 'normalized issues with suggested fixes', implying a read-only behavior, but the phrase 'drives repair loops' introduces ambiguity about whether it actually mutates state. It does not explicitly state that the tool doesn't modify the project, nor does it mention permissions or side effects. This is a notable gap.

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 paragraph of three sentences that front-loads the purpose ('Validate a local project folder/.zip or file map...'). It avoids redundancy and packs relevant information efficiently, though the opening '[Arch Optimize]' and 'drives repair loops' add slight verbosity without much new 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?

With 4 optional params, nested objects, and no output schema, the description covers the input sources and return type ('normalized issues with suggested fixes') but omits prerequisites like a platform connection (sibling platform_connect) and the detailed structure of the returned issues. It is adequate for a simple validation tool but leaves some operational context to inference.

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 minimal parameter detail—it maps 'path' to 'local project folder/.zip' and 'files' to 'file map', but does not elaborate on 'data' or 'projectId' beyond what the schema already provides. It doesn't degrade or enhance the schema 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 states a specific verb (validate) and a resource (local project folder/.zip or file map) that distinguishes it from sibling tools like debug_* and platform_arch_auto_loop. However, it also includes vague phrases like 'inspects compiler-visible models' that could overlap with platform_package_model, so it's clear but not fully crisp.

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 in ABL repair/eval loops', giving a clear context for when to invoke it. It does not name alternatives or exclusions, but the context is concrete enough for an agent to decide. A 4 is appropriate for clear usage context without explicit '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 full behavioral burden and does real work: it discloses that versions are immutable, that publish operates on the 'current draft with raw-DSL hash guard' (mapping to expectedDraftSourceHash), and critically that legacy create/promote do NOT perform HTTP calls but return migration guidance — preventing an agent from assuming a write succeeded. Gaps remain (auth requirements, return format, failure behavior), but for an annotation-less tool these disclosures are genuine value-adds.

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 core message 'Manage immutable agent versions' is front-loaded, but the leading '[Arch Build] Arch creates and changes...' preface is a meandering domain statement that repeats 'Arch' and adds little selection value. The structure is undermined by the action-list mismatch: it enumerates six actions while the schema has eight, and the legacy create/promote sentence arrives separately, forcing the reader to reconcile a self-inconsistent account. Moderate efficiency with a structural seam.

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?

This is a high-complexity dispatch tool: 8 enum actions, 10 parameters, 3 required, no output schema, and no annotations. The description covers the action surface, immutability, and legacy behavior, which is a solid core. But it leaves return format entirely unspecified (no output schema to compensate) and does not map which parameters apply to which action — an agent must infer param-action coupling from the schema alone. Reasonably complete on actions, lacking on call-level detail.

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 90% (high, above the 80% threshold), so the baseline is 3 even with no parameter prose in the description. The description does add context by tying expectedDraftSourceHash to the publish 'raw-DSL hash guard' and flags the promote 'status' param as legacy via the migration-guidance note. It does not restate or enrich the other parameters, but that work is already done well in the schema.

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

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

"Manage immutable agent versions" states a specific resource and operation set, distinguishing it from sibling platform_* tools like platform_agents and platform_deployments. However, the enumerated action list (list, get, publish, qualifications, audit, diff) omits 'create' and 'promote' that appear in the schema enum, and the final sentence then references 'Legacy create/version-promote' — an internal inconsistency that slightly muddies the intended action surface.

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

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

No explicit when-to-use or when-not-to-use guidance versus the 40+ sibling tools. The description mentions that legacy create/promote 'return migration guidance without HTTP calls,' which is a soft excluder, but it never states which tool should handle version creation or promotion now, nor when to prefer platform_versions over platform_deployments/platform_agents. Usage context is only implied from the resource name.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It provides detailed edge sourceHandle rules and node types, which is technical behavior, but it does not mention safety aspects like destructive nature of delete, side effects of publish, or permissions. The schema covers confirm for delete, but the description itself omits such cautions.

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 logically organized: purpose, actions, node types, edge rules. It front-loads the main function and packs relevant details without excessive fluff. However, it is long and could benefit from bullet points or clearer separation, so not 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 18 parameters and no output schema, the description does not explain return values or outcomes for actions like list, get, or execute. It also lacks guidance on pagination beyond schema parameters. While it covers many technical details, it misses high-level context about what each action yields, making it incomplete for an agent.

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

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

Schema description coverage is 83%, so the schema already documents most parameters. The description repeats the sourceHandle rules that are also in the schema and lists node types that appear in the nodeType description. It adds no new parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the resource (node-based workflows) and a comprehensive list of actions (list, get, create, update, publish, execute, create_tool, delete), distinguishing it from sibling tools like platform_projects and platform_agents. It also details node types and edge rules, making its scope unmistakable.

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 lists actions but does not explicitly state when to use this tool versus alternatives. It mentions create_tool as a way to expose workflows as ProjectTools, but lacks clear 'use this when' or 'use this instead of' guidance. With many platform_* siblings, explicit differentiation 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 for behavioral disclosure. It reveals that switch atomically authorizes and changes the authenticated socket, credentials, and subsequent calls, and that current decodes from a JWT. It also discloses that responses include activeTarget and contextVersion, which is beyond the schema. These details give the agent a clear picture of side effects without needing additional 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 description is reasonably concise but opens with an extraneous sentence about Arch's general capabilities ('Arch creates and changes projects, agents, tools, configuration, versions, and deployments') that is not specific to this tool. While the core content is well-structured with 'Manage workspaces' and an action list, this preamble adds noise and could be trimmed. The description remains clear but not optimally 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?

For a tool with three actions, two parameters, and no output schema, the description covers the essential context: what each action does, the required input for switch, and key response fields (activeTarget, contextVersion). It mentions the workflow of surfacing the active environment after a switch, which is useful for an agent. It does not detail error conditions or exhaustive response structures, but given the tool's complexity, 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 coverage is only 50% (only tenantId has a description), but the tool description compensates by explaining the action enum values in detail and clarifying that tenantId is required for switch. This adds meaning beyond the schema, such as that list returns workspaces with an active flag. The description effectively documents both parameters without leaving gaps.

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 manages workspaces (tenants) and enumerates three specific actions (list, switch, current) with brief explanations. This explicitly differentiates it from sibling tools like platform_projects or platform_config, which handle other resources. The verb 'manage' plus the action list leaves no ambiguity about what the tool 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 description explains when to use each action (e.g., list to see all workspaces, switch to change active, current to inspect the active one) and even suggests surfacing the active environment after a switch. However, it does not explicitly mention when not to use this tool or point to alternative tools, leaving some inference to the agent. Siblings like platform_projects exist but are not compared, so guidance on choosing between them is implicit rather than explicit.

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