InsideOut (Riley)

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

The description adds substantial behavioral context beyond the annotations: it fetches temporary read-only credentials securely, queries the AWS API directly, offers different response tiers (summary/detail/raw) for token efficiency, works after failed deploys, and discloses specific IAM permissions required for cost-explorer actions. No contradiction with annotations.

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

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

The description is long but well-structured with bold headings, bullet lists, and examples. Every section (prerequisite, response tiers, services, metrics, billing, examples) serves a purpose. It is front-loaded with the prerequisite and includes useful details without being bloated, though slightly dense.

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—29 services, multiple response modes, cost queries, metrics—the description covers all major aspects: prerequisite, usage flow, response tiers, service list, metrics/billing specifics, and examples. Since there is no output schema, it adequately compensates by describing the three return levels (summary, detail, raw).

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

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

Although the schema has 100% coverage, the description adds meaning by mapping the detail and raw flags to response tiers, clarifying that filters are optional despite being listed as required in the schema, and providing concrete examples for actions and filters. It also reinforces the session_id token warning, adding practical usage context beyond the schema.

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

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

The description clearly states it inspects AWS infrastructure for a deployed project and specifically 'Inspect deployed AWS resources after a deployment attempt.' It distinguishes itself from siblings by focusing on AWS, requiring a deployment attempt, and noting it works even after failed deploys to inspect orphaned resources. This is a specific verb+resource with clear 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?

It explicitly says 'Use this tool when the user asks about the status or details of their deployed infrastructure' and gives a clear prerequisite: check convostatus for hasDeployAttempt=true. It also explains it works after failed deploys. However, it does not explicitly name alternatives (like gcpinspect for GCP) or provide when-not-to-use guidance, so it falls 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?

Annotations declare readOnlyHint=true and openWorldHint=true, and the description adds substantial behavioral context beyond this: partial failure is expected, the response format includes truncated entries past a 512 KB cap, credential fetch failures leave certain probes succeeding, concurrency cap of 8, and summarized responses. This fully discloses operational behavior without contradicting annotations.

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

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

Though lengthy, the description is exceptionally well-structured with headers (PREREQUISITE, BUDGETS, PARTIAL FAILURE, REQUIRES, Supported services, EXAMPLES) and each sentence is information-dense. No filler or redundancy; the length is justified by the tool's complexity and the need to convey failure modes and constraints.

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 explains the return format: an ordered results array with {index, service, action, ok, result, error}. It covers prerequisites, budgets, supported services, and provides two concrete examples. This makes it fully self-contained for an agent to invoke correctly, despite the tool's complexity.

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

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

The input schema already covers both parameters with 100% coverage, providing a baseline of 3. The description enriches parameter meaning by explaining the subs array's concurrency (8), per-sub timeout (30s), total wall-clock (60s), response truncation behavior, and the session_id token requirement. It also clarifies that subs entries keep envelope fields even when truncated, adding valuable context beyond the schema.

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

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

The description opens with 'BATCH INSPECTION: run up to 32 AWS inspect probes in one call', providing a specific verb and resource with a clear scope. It explicitly contrasts with the singular awsinspect tool, stating it is for batch checks while awsinspect is for discovery and single-resource detail, which distinguishes it from siblings.

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

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

The description gives explicit when-to-use guidance: 'Use this when you need to check more than ~3 resources.' It also provides exclusions and alternatives: 'For a specific service's actions, use awsinspect (singular) with action="list-actions" — batch is not the place for discovery' and 'use singular awsinspect when you need full metadata or raw API output for one resource.' It additionally states prerequisites via convostatus.

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

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

The annotations already declare readOnlyHint=true, which is consistent with the described wait operation. The description adds meaningful context beyond annotations by specifying the return format ('Returns the same format as convoreply when successful') and clarifying that it does not resend the message, which enhances transparency about the tool's runtime 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 well-structured and front-loaded: the first sentence states the purpose, followed by a clear 'USE THIS TOOL WHEN' section, then required/optional parameters, and a return format note. Every line serves a purpose with no redundant content, making it concise yet comprehensive.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description covers essential aspects: purpose, trigger, requirements, timeout limits, and return format. A minor gap is lack of guidance on repeated timeouts, but the read-only/open-world annotations and sufficient detail make it complete for most agent decision-making.

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

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

Schema coverage is 100%, so all three parameters are already thoroughly described in the input schema (e.g., timeout max, session_id pattern). The description organizes them into REQUIRES/OPTIONAL and repeats the same context from the schema, adding little new semantic value beyond the structured definitions.

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

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

The description clearly states the tool's action: 'Wait for a pending response from Riley after a convoreply timeout.' This is a specific verb ('wait') with a clear resource and trigger, and it distinguishes itself from convoreply by noting 'without resending the message,' making the purpose unambiguous and differentiated.

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

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

The description explicitly provides a usage condition: '🎯 USE THIS TOOL WHEN: convoreply returned a timeout error.' It also explains the benefit ('continue waiting... without resending') and outlines prerequisites and optional parameters, giving clear guidance on when to use it versus alternatives.

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

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

The description reinforces the readOnlyHint annotation with 'Read-only; never mutates session state,' and adds behavioral nuance beyond annotations by warning that the session_id token suffix is a credential and should never be stripped. This provides useful operational context without contradicting 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 slightly long but well-organized, starting with a bolded 'INSPECTION' header and using bullet-like lines for related tools. Each sentence provides distinct value—scope, return content, companion tools, and usage trigger. It is front-loaded and structured for quick scanning, though it could be trimmed slightly without losing meaning.

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

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

Given there is no output schema, the description thoroughly explains return values: 'full message history (user / assistant / tool turns) plus the session's meta — workflow step, cloud, deployment status, drift state.' It also covers required input format, usage context, and read-only behavior, making the tool fully understandable without external documentation.

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

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

Schema coverage is 100% with a clear pattern and description for session_id. The description adds extra meaning by explaining the token suffix is part of the session credential and must be preserved, which is critical for correct invocation. While the schema already documents the format, the description elevates the parameter's semantic importance.

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: 'View a session's conversation transcript and metadata' with a specific verb and resource. It explicitly distinguishes itself as 'the transcript-reader companion to the other read tools' and lists sibling tools for alternative use cases, making it easy to select correctly.

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 guidance: 'Use it when a user asks 'what did I say earlier?' or you need to retrace why the session ended up where it did.' It also names alternatives (convostatus, tfruns, stackversions) for other intents and states it is read-only, giving clear selection criteria.

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

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

The description discloses critical behaviors beyond the annotations: the session_id format with a ?token= suffix and its necessity to avoid 401s, the instruction to never strip or paraphrase it, and the warning that Riley will ask questions the agent must forward rather than answer. It also notes the source parameter controls the 'Open {IDE}' button. These add substantial behavioral detail that annotations (openWorldHint: true, destructiveHint: false) do not convey.

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

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

The description is longer than typical but each section serves a purpose: workflow label, session handling, usage trigger, and per-parameter guidance. It is structured with headers and bolded warnings, making it scannable. Minor redundancy exists (e.g., session_id importance repeated), but overall it is efficient for a complex tool.

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

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

With no output schema, the description explains the expected response ('clean message from Riley' and 'session_id in the response metadata'). It covers the full context: initialization, user interaction, downstream tool requirements, parameter semantics, and even points to 'workflow.usage prompt' for further guidance. For a session-starting tool with 3 optional parameters, this is complete.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description enriches each parameter: project_context includes a detailed example and explicit exclusions (no credentials/PII), source includes auto-detection guidance and a list of accepted values, and github_username explains its pre-fill behavior. This goes beyond the schema's short descriptions, though the schema already handles basic 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 explicitly states 'WORKFLOW: Step 1 of 4 - Start infrastructure design conversation' and 'Open an InsideOut V2 session and receive the assistant's intro message.' This clearly identifies the verb (start/open), resource (infrastructure design conversation/session), and how it differs from siblings like convoreply or tfgenerate (it is the initial session setup step).

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

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

The description provides explicit when-to-use guidance: 'Use when the user mentions keywords like: 'setup my cloud infra', 'provision infrastructure', 'deploy infra', 'start insideout', 'use insideout', or similar intent to begin infra setup.' It also gives workflow context (step 1 of 4) and indirectly distinguishes it from alternatives by requiring the session_id for subsequent tools. However, it does not explicitly state when NOT to use this tool versus others, and relies on 'Examine workflow.usage prompt' for broader 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?

The description goes far beyond the annotations (openWorldHint, destructiveHint) by disclosing critical behavioral traits: the agent must never answer Riley's questions itself and must forward them to the user. It also reveals response signals like [TERRAFORM_READY: true] and [[BUTTON_TF_APPLY]] that trigger subsequent actions, providing essential non-obvious 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 long but well-organized with clear headers, bulleted critical warnings, and key signal sections. Every section provides actionable guidance without fluff; the repeated emphasis on not answering user questions is essential and appropriately highlighted.

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

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

Despite having no output schema, the description fully explains what the response will contain (TERRAFORM_READY, BUTTON_TF_* signals) and how to proceed based on those signals. It also gives a tip to use convostatus for progress checks, making it contextually complete for an AI agent navigating the workflow.

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

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

Although the schema covers 100% of parameters, the description adds substantial contextual guidance: session_id must be passed exactly as returned including the token suffix, timeout should be set to 50 for Cursor, and project_context should only contain genuinely new details after convoopen, with explicit warnings not to resend prior context or scan files. This enriches parameter meaning beyond the schema.

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

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

The description clearly states it sends a user message to the active InsideOut session and receives the assistant reply, explicitly positioned as 'Step 2 of 4' in the workflow. This distinguishes it from siblings like convoopen (initiate) and convostatus (check progress).

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

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

The description explicitly states when to use the tool (after convoopen, before tfgenerate) and when not to (do not call tfgenerate until this tool returns). It names alternatives (convostatus) and provides the workflow phase sequence: conversation → tfgenerate → tfdeploy.

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 readOnlyHint=true, and the description reinforces a read-only inspection role. It adds context about data availability (pricing when available), phase indicators, and that the session_id is a credential that should not be altered—useful beyond annotations.

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

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

The description is well-structured with markdown sections and front-loaded purpose. It is somewhat lengthy but every section contributes meaningful detail about return contents and usage, so it 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?

Given the tool's read-only nature, no output schema, and simple parameter set, the description covers return content comprehensively (components, config, pricing, phases) and mentions constraints (required session_id format). Minor gaps like error behavior or further alternatives prevent a 5.

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 meaning by emphasizing that session_id must be passed exactly as returned (including token suffix) and explaining job_id's optional role—valuable behavior beyond schema 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 verb+resource: 'View the current infrastructure stack for a session' and breaks down the returned content (Components, Config, Pricing, Phase Indicators). This distinguishes it from sibling inspection tools like awsinspect or convoinspect, which focus on different resources.

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 guidance with example user queries ('what is my current stack?') and notes the required session_id. While it does not list alternatives or exclusions, the context is clear enough for an agent to select this tool appropriately.

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

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

Beyond the annotations (openWorldHint, idempotentHint, destructiveHint false), the description discloses polling behavior, timeout handling, secure credential handling, and the prerequisite of showing the URL. It explains that the tool 'polls until credentials appear' and that credentials are 'handled securely and only used for deployment and management 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 well-structured with a workflow section and important notes, and it front-loads the core purpose. While it is somewhat lengthy, each sentence carries useful information; minor redundancy exists with parameter details already in the schema.

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 parameters, no output schema, and a required user interaction, the description is complete: it covers the trigger condition, workflow steps, prerequisites, and follow-up action (call tfdeploy after credentials are found). The agent has all necessary context to invoke the tool correctly.

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

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

Schema description coverage is 100%, with each parameter (cloud, timeout, session_id) already described in detail including defaults and format constraints. The description repeats these details without adding new semantics beyond what the schema provides, 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: 'Wait for the user to securely connect their cloud account and subscribe to Luther Systems. Polls until credentials appear on the session.' It uses a specific verb and resource, and distinguishes itself from siblings like tfdeploy by tying its use to specific error conditions from tfdeploy.

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?

Explicit guidance is given: 'USE THIS TOOL WHEN: tfdeploy returns an auth_required, no_credentials, or credentials_expired error.' It also includes a workflow with prerequisites and a warning: 'Do NOT call this tool without first showing the connect URL to the user.' This fully covers when and how to use it versus alternatives.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that it fetches temporary read-only credentials securely, works after failed deploys to inspect orphaned resources, reverts to a summary by default for token efficiency, lists required IAM roles, and explains specific metric behaviors (e.g., Secret Manager returns operational health without time-series, Bastion is an alias with limitations). This is 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 description is well-structured with clear sections (PREREQUISITE, RESPONSE TIERS, METRICS, BILLING, EXAMPLES) and is front-loaded with the core purpose. It is long but every section provides substantive information. Minor repetition at the start ('INSPECTION', 'Inspect GCP infrastructure', 'Inspect deployed GCP resources') costs it a full 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?

For a complex tool with 6 required parameters, no output schema, and many supported services, the description is remarkably complete. It covers prerequisites, response tier behaviors, IAM role requirements, billing specifics, metric breakdowns, and edge cases like failed deployments and orphaned resources. This is more than sufficient for an agent to correctly invoke the tool.

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

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

The schema already provides 100% parameter coverage with descriptions and examples, so the baseline is 3. The description adds valuable nuances: the response-tier semantics for detail/raw, filter JSON examples, the explicit instruction to pass session_id exactly as returned, and service-specific action hints. This exceeds the baseline without redundancy.

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

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

The description starts with 'INSPECTION: Inspect GCP infrastructure for a deployed project' and later states 'Inspect deployed GCP resources after a deployment attempt.' This clearly identifies a specific verb (inspect), resource (GCP infrastructure), and scope (post-deployment). It also distinguishes itself from siblings like awsinspect (AWS counterpart) and gcpinspect_batch (batch variant).

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

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

The description explicitly says 'Use this tool when the user asks about the status or details of their deployed GCP infrastructure.' It provides a prerequisite (hasDeployAttempt=true), references convostatus for verification, and includes concrete usage examples for services and actions. It also advises using action='list-actions' for discovery, which is a clear usage pattern.

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 declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral detail beyond those: credential fetch fan-out, 30s/60s timeouts, concurrency cap 8, 512KB response cap with truncated=true, and the expectation that 'PARTIAL FAILURE IS EXPECTED.' It also explains credential-failure behavior and summarized responses, which are not visible from annotations or 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?

Although long, the description is organized with clear section headers (PREREQUISITE, BUDGETS, PARTIAL FAILURE, REQUIRES, EXAMPLES) and every sentence carries operational value. Front-loaded purpose and usage guidance prevent wasted reading, and examples illustrate real call patterns compactly.

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 high complexity, no output schema, and many constraints, the description covers prerequisites, limits, error semantics, response structure, and alternatives comprehensively. It even specifies the ordered results array with envelope fields {index, service, action, ok, result, error}, ensuring an agent knows what to expect and how to process partial failures.

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, but the description significantly enriches parameter semantics. For session_id, it insists 'pass back EXACTLY as returned, including the ?token=... suffix' and 'never strip it when summarizing.' For subs, it details the result envelope, truncation behavior, and credential-fetch edge cases, adding operational meaning beyond the schema's field definitions.

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

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

The description opens with 'BATCH INSPECTION: run up to 32 GCP inspect probes in one call,' which clearly states the verb, resource, and batch scope. It distinguishes from sibling gcpinspect by emphasizing the multi-probe batching capability and explicitly names the singular alternative for single-resource inspection.

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

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

The description provides explicit when-to-use guidance: 'Use this when you need to check more than ~3 resources.' It also gives clear when-not-to-use cases, such as using 'gcpinspect (singular) with action="list-actions"' for discovery, and notes the prerequisite deploy attempt via convostatus. Alternatives are named and differentiated.

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

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

The description discloses behavioral traits beyond the annotations: 'Responses include hints with next_actions and related_tools.' This adds useful context about the output format and the guidance nature of the tool. The readOnlyHint and openWorldHint annotations are consistent with the description, and no contradictions are present.

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

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

The description is three concise sentences, front-loaded with the main purpose, then usage, then behavioral details. Every sentence adds value with no repetition or filler. It is appropriately sized for the tool's simplicity.

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 help tool with one optional parameter and comprehensive annotations (readOnlyHint, openWorldHint), the description covers purpose, usage, sections, and response hints. It is complete enough for an agent to select and invoke the tool correctly, even without an output schema.

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 optional parameter 'section' is fully described in the input schema, including its enum values and behavior when omitted ('returns a compact overview (~500 tokens)'). The tool description merely reiterates the section list and the compact vs detailed distinction, adding little beyond the schema's coverage.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Get workflow guidance for using InsideOut infrastructure tools.' It distinguishes itself from all sibling tools as the only help/guide tool, and the title 'Workflow Guide' reinforces this 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 explicit usage patterns: 'Call help() for a compact overview, or help(section=...) for a detailed guide.' This gives clear context on how to invoke the tool, though it doesn't name alternatives because none exist. It also lists the available sections, which aids in selecting the right invocation.

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 readOnlyHint and openWorldHint, but the description adds substantial behavioral detail: the return structure (component/field/pricing changes), default comparison semantics, the fact that pending drafts are not used, and the `session_id` credential requirement. These go well beyond the annotations and clarify tricky state-dependent 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 compact and organized: a top-line summary, a defaults paragraph, an explicit-version sentence, and a requirement line. The reference to '#1392' is minor noise but does not detract significantly. Overall, it is appropriately sized with no wasted 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?

With no output schema, the description compensates by explaining what the tool returns (component-level changes, field-level details, pricing deltas). It also covers default behavior, state-dependent baselines, and required credentials, making it sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, with each parameter already well-documented (defaults, types, patterns). The description reinforces the defaults for from_version/to_version but adds no new semantic detail beyond the schema. This meets the baseline of 3 for high schema coverage.

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

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

The description states a specific verb+resource: 'Structured diff showing what would be deployed if the user ran tfdeploy now.' It clearly distinguishes from siblings like stackversions (listing versions) and tfplan (planning a run), making the tool's purpose unambiguous.

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

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

Provides clear context for when to use: to preview deployment impact, with defaults comparing last deployed version to current live design. It also explains edge cases (empty baseline before deployment or after destroy) and prerequisites (session_id). However, it does not explicitly name alternative tools or state when not to use it, so it falls 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?

The description adds valuable behavioral details beyond the annotations: it copies components/config/pricing, updates in-place if a draft exists, and requires a session_id from convoopen. These specifics complement the idempotentHint and destructiveHint annotations without contradicting them.

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

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

The description is compact and front-loaded with the primary purpose, followed by necessary usage details and parameter requirements. Every sentence adds value without unnecessary fluff.

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

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

Given the moderate complexity, complete schema, and presence of annotations, the description provides sufficient context for invocation: what it does, how it behaves with existing drafts, and what to do first. It does not describe return values, but with no output schema this is a minor gap.

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

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

Schema description coverage is 100%, and the schema already fully documents both parameters with format details and usage. The description only repeats the requirement ('REQUIRES: session_id... version') without adding new semantic information beyond the schema.

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

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

The description clearly states a specific action: 'Create a draft version by reverting to a previous version's config.' It names the resource (stack version), the verb (revert/create), and distinguishes itself from siblings like stackversions (list versions) and stackdiff (compare versions).

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 instructs to 'Use `stackversions` first to find available version numbers,' providing a clear prerequisite. It also explains the single-draft rule, but does not explicitly contrast with alternatives or state when not to use this tool beyond the prerequisite.

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 readOnlyHint=true, so the safe-read nature is covered. The description adds useful behavioral context beyond this: newest-first ordering, included statuses and timestamps, and the critical prerequisite that session_id must include the ?token=... suffix and be passed exactly. The credential-handling emphasis is especially valuable, as it prevents a common caller error.

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

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

The description is tightly structured in four short sentences: main action, output highlights, use cases, and a required-parameter note. Every sentence earns its place, and the most critical information is front-loaded in the first sentence. No fluff or redundant phrasing.

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

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

Despite having no output schema, the description explicitly lists the core returned fields: version number, status (draft/confirmed/applied), change summaries, and timestamps. It also includes the necessary input prerequisite and intended usage. For a read-only list tool with one parameter, this gives an agent enough context to invoke it correctly and interpret the result.

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 schema's session_id description is already extremely detailed—including the exact format, token suffix, and instruction never to strip it. The description merely repeats 'REQUIRES: session_id from convoopen response (format: sess_v2_...)' without adding new meaning beyond the schema. Therefore, 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 opens with a specific verb and resource: 'List all stack versions for a session (newest first).' It clearly differentiates this tool from siblings like stackdiff or stackrollback by focusing on version history listing. The output contents and ordering are explicitly stated, leaving no ambiguity about the tool's function.

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 when-to-use guidance: 'see the design history, review what changed between iterations, or find a version number to roll back to.' It does not explicitly name exclusions or alternatives (e.g., stackrollback for actual rollback), but the use cases are well-defined and align with the tool's purpose.

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

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

Annotations only provide openWorldHint and destructiveHint, so the description carries the burden of behavioral context. It adds meaningful detail: initiator semantics ('user' vs 'agent'), the credential warning to never strip the session_id token suffix, and the source default. It doesn't describe post-submission behavior, but still adds substantial value beyond annotations.

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

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

Front-loaded with a clear purpose statement, then structured requirements, categories, initiator explanation, and concrete examples. Every section earns its place and the length is justified by the added explanatory 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?

For a 7-parameter feedback tool with full schema documentation and no output schema, the description covers required and optional fields, category enumerations, initiator flow, and an important credential-handling caveat. It is complete enough for an agent to invoke the tool correctly without additional clarification.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the initiator field with concrete examples, noting source default 'mcp', and emphasizing the exact session_id format with token suffix. It largely restates schema information but enriches it with usage context.

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

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

Description explicitly states 'Submit feedback, bug reports, or feature requests to Luther Systems' and lists categories such as bug_report and feature_request. This gives a specific verb + resource and clearly distinguishes it from all sibling infrastructure 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?

Description says 'Use this tool to forward user feedback directly to the Luther Systems team' and provides examples for both user and agent initiators. It does not explicitly state when not to use the tool or mention alternatives, but the context and examples make intended usage clear.

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

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

Annotations already declare destructiveHint and openWorldHint; the description adds substantial behavioral context: long-running (15+ minutes), single-flight guard with tf_job_conflict response, drift-fails-by-default behavior, and credential flow with connect_url. This goes well beyond the annotations.

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

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

The description is long but well-structured with clear sections for workflow, options, and credential flow. While some redundancy with schema exists, most content earns its place by providing operational context.

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

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

For a destructive, long-running tool with no output schema, the description covers expected return behavior, failure mode (tf_job_conflict), prerequisite session_id, optional parameters, and credential flow. It provides a complete operational picture.

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

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

Schema provides 100% coverage, but the description clarifies session_id format and the relationship between plan_id and project_id. However, it contradicts the schema on sandbox default: description says default false, schema says default true for MCP. This is a misleading discrepancy that could cause incorrect invocation, so score is reduced.

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 deploys infrastructure via a Terraform job, explicitly positioning it as Step 4 of a 4-step workflow. It distinguishes itself from siblings like tfplan and tfgenerate by stating it initiates the actual deployment after files have been generated.

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 workflow context: after generation, preview-then-apply sequence (tfplan → tflogs → tfdeploy), and clear instructions for conflicts (don't retry, attach with tfstatus/tflogs or use force_new). Also includes credential flow prerequisites and a direct 'Do NOT call credawait without showing URL' exclusion.

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?

Beyond the destructiveHint annotation, the description discloses long-running job behavior, single-flight constraint, conflict response format, force_new override semantics, and that hasDeployment is set to false after completion. This adds meaningful context beyond the structured annotation.

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

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

The description is well-structured with clear section labels and is front-loaded with the purpose. However, it is somewhat verbose, repeating 'tfstatus/tflogs' multiple times and including detailed conflict handling that could be condensed. Still, every sentence carries relevant information.

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

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

For a destructive, long-running tool with no output schema, the description covers prerequisites, monitoring, conflict handling, force_new use, and post-completion state changes. It provides enough context for an agent to use the tool safely and effectively.

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 schema already fully documents session_id including the token suffix warning. The description adds a usage caveat for force_new ('Use only when the existing run is provably wedged'), but otherwise does not substantially exceed the schema. Baseline 3, raised to 4 for the caveat.

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

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

The description opens with 'DESTROY: Tear down previously deployed infrastructure' which is a specific verb+resource statement. It clearly distinguishes this tool from siblings like tfdeploy (deploy) and tfplan (plan) by focusing on destruction and requiring a prior successful deployment.

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

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

Provides explicit guidance: requires a session_id from convoopen, prerequisites (prior successful deployment), and explains single-flight conflict handling with tf_job_conflict and how to use force_new as an override. It also directs monitoring via tfstatus/tflogs.

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

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

The description adds significant behavioral context beyond the annotations: read-only guarantee, single-flight concurrency guard, conflict error behavior (tf_job_conflict), and the force_new override caveat. There is no contradiction with the provided annotations.

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

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

The description is well-structured with clear labels (REQUIRES, PREREQUISITE, OPTIONAL) and front-loaded key facts. It is longer than minimal, but every sentence provides operational value and there is no filler.

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

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

With no output schema, the description still explains the return value (job_id), prerequisites, single-flight behavior, and follow-up actions. It gives enough context for an agent to invoke the tool correctly and interpret the result.

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

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

Although the schema fully documents both parameters, the description adds crucial semantics: session_id must be passed back exactly as returned (including the ?token= suffix and never stripped), and force_new should only be used when the existing run is provably wedged.

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 ('Run') and clearly names the resource ('drift detection check'), stating it compares deployed infrastructure to the expected Terraform state. It distinguishes itself from siblings by emphasizing read-only behavior and pointing to tflogs for streaming results.

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

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

It explicitly states when to use the tool, its prerequisites (prior deployment with project_id), required session_id source, and single-flight behavior. It also names alternatives and follow-up actions (tflogs, tfstatus, tfdeploy) and gives a conditional directive for force_new.

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

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

The description discloses that the default response is a summary table plus a download URL (to keep code out of LLM context), and that include_code:true is a fallback for sandbox/security failures. It also outlines the post-call workflow, including asking the user for the save directory and handling curl/unzip failures, providing significant behavioral context beyond the annotations.

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

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

The description is well-structured with sections and front-loaded purpose, but it is verbose. The critical workflow and tips add operational value, though some repetition (e.g., 'Generate Terraform' appears multiple times) could be trimmed. Still, each section earns its place for an agent.

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 is part of a complex workflow, but the description covers prerequisites, default and fallback return behaviors, the post-invocation user-confirmation step, and the handoff to tfdeploy. It also references the workflow.usage prompt for further context, making it comprehensive for safe and 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 100%, but the description enriches both parameters: session_id must be passed exactly as returned from convoopen (including the ?token=... suffix) and is tied to the terraform_ready prerequisite; include_code is explained as a fallback for environments that cannot read on-disk archives. This exceeds the schema details.

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 'Generate Terraform files from an InsideOut session that has completed infrastructure design', specifying the verb, resource, and context. It also identifies itself as Step 3 of 4, distinguishing it from siblings like tfdeploy and tfplan.

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 'USE THIS TOOL WHEN' section explicitly defines the trigger conditions: after convoreply returns terraform_ready=true, or when the user requests terraform generation. It also provides exclusions (DO NOT call while convoreply is running) and directs to tfdeploy for the next step, giving clear usage boundaries.

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?

Beyond the readOnlyHint annotation, the description discloses REST vs SSE streaming, pagination with last_event_id, response field meanings, and a context window warning. This is rich behavioral detail that helps the agent understand side effects and limitations.

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 organized with clear sections (MONITORING, PAGINATION, RESPONSE FIELDS, REQUIRES/OPTIONAL) and front-loaded with a summary. Every sentence adds value without fluff, making it easy to parse despite 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?

With no output schema, the description fully explains the response fields (logs, last_event_id, complete, total_logs) and provides a step-by-step pagination algorithm. It also warns about context-window risk. This is complete for an agent to use correctly.

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

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

Schema description coverage is 100%, but the description adds critical semantics: the session_id token suffix warning ('never strip it when summarizing'), tail for context, and pagination cursor behavior. This goes well beyond the schema 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 'Fetch Terraform deployment logs' with a specific verb and resource. It differentiates between running and completed jobs and mentions pagination, making it distinct from sibling tools like tfstatus or tfruns.

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

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

The description provides explicit usage context: requires session_id from convoopen, optional job_id discoverable via tfruns, and detailed pagination steps. It does not explicitly say 'when not to use this tool', but the instructions are clear and reference alternatives.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds useful behavioral details: sensitive outputs are redacted as '(sensitive)', and outputs are from the latest successful deploy unless a job_id is specified. This goes beyond what annotations alone provide, with no contradictions.

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

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

The description is well-organized with an initial purpose line, a bullet-like 'REQUIRES/OPTIONAL' section, and a clear default behavior note. While somewhat verbose, each sentence contributes useful information without fluff, making it appropriately sized and front-loaded.

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

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

Given the tool's modest complexity (3 params, no output schema, read-only annotations), the description covers prerequisites, defaults, filtering options, and the output format (structured values with redaction). It could expand on the exact structure of the returned output, but for an inspection tool this is sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description supplements the schema by explaining the exact format for session_id (including the ?token= suffix and not stripping it), providing concrete examples for lifecycle values, and clarifying job_id's default behavior. This adds meaningful guidance beyond the raw schema.

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

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

The description explicitly states 'Retrieve Terraform outputs from a completed deployment' with an 'INSPECTION:' prefix, clearly identifying the verb and resource. It distinguishes this from sibling tools like tflogs (logs) and tfstatus (status) by specifying that it returns output values such as VPC IDs and endpoints.

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 usage context: it retrieves outputs after a successful deploy, defaults to the latest successful deployment, and allows optional job_id for specific deployments. It also states the prerequisite session_id from convoopen. It doesn't explicitly name alternatives, but the context is sufficient to know when to use it.

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

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

Beyond annotations (openWorld, idempotent, non-destructive), the description discloses critical behavior: single-flight constraint, conflict return (tf_job_conflict), requirement to pass session_id exactly, and details about sandbox vs real execution. No contradiction with annotations; adds significant 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?

Although longer than average, every sentence serves a purpose. Structured with labeled sections (PREVIEW, SINGLE-FLIGHT, REQUIRES, OPTIONAL, CREDENTIAL HANDLING) for skimmability. No wasted words.

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

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

For a complex tool with no output schema, the description covers return values (job_id, plan_id, project_id), conflict handling, prerequisites, and workflow handoff to other tools. Fully self-contained for an agent to invoke correctly.

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

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

While schema coverage is 100%, the description enriches each parameter: sandbox is explained as 'cheap sandbox template (testing only)', force_new as bypassing the single-flight guard, and session_id is emphasized with 'pass back EXACTLY... never strip it when summarizing.' This goes beyond schema descriptions.

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

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

The description clearly states the tool's action: 'Run terraform plan to preview infrastructure changes' and 'without applying any changes.' It explicitly differentiates from sibling tools by specifying that tflogs streams output and tfdeploy applies the plan with plan_id.

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 workflow guidance: run plan first, then use tfdeploy with plan_id to apply. Also specifies when to use alternatives (attach with tfstatus/tflogs on conflict) and gives context for optional parameters (sandbox for testing, force_new for wedged runs). Credential prerequisites are clearly 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 readOnlyHint and openWorldHint, so the description does not need to restate safety. It adds the 'INSPECTION' label, the return contents, and the prerequisite session_id format. The minor inconsistency between the description's types (apply/destroy) and the schema's types (apply/destroy/plan/drift) is a small transparency gap but not a contradiction with annotations.

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

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

The description is compact and well-sectioned (INSPECTION, Returns, Use this, REQUIRES). It is front-loaded and every section serves a purpose, though there is slight redundancy between 'List all runs' and 'Returns ... for every run'.

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

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

For a simple list tool with one parameter, no output schema, and readOnlyHint annotations, the description adequately covers return values, use cases, and the required session ID source. The omission of 'plan/drift' types from the description is a minor gap, but overall the tool is easy to invoke correctly.

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

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

Schema description coverage is 100% and already thoroughly explains the session_id parameter, including the exact format and the token warning. The tool description only repeats 'REQUIRES: session_id from convoopen response' without adding new semantic information, so it stays at 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 uses a specific verb+resource: 'List all Terraform deployment runs for a session' and specifies the returned data (job IDs, statuses, types, timestamps). It clearly differentiates this from sibling tools like tfdeploy or tfdestroy by focusing on history listing rather than execution.

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

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

It states concrete use cases: 'see deployment history, find job IDs for log inspection, or check which deployments succeeded or failed.' This gives clear context for when to use the tool, though it does not explicitly mention alternatives or when not to use it.

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

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

Beyond the readOnlyHint annotation, the description discloses rich behavioral details: it returns job status/job_id/metadata without streaming logs, and explains the distinct LIVENESS timestamps (updated_at vs last_refresh_at) including their semantics and when last_refresh_at may be absent. This is substantial added context about response behavior and poll semantics.

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

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

The description is well-organized with clear sections (MONITORING, REQUIRES/OPTIONAL, LIVENESS, TIP) and front-loads the core purpose. While the LIVENESS section is detailed, every sentence contributes valuable behavioral context. It is structured efficiently and not overly verbose.

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

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

For a read-only status tool with no output schema, the description covers all essential aspects: what it does, when to use it, how parameters are obtained, what the response contains, and caveats about timestamps. It also names the relevant sibling tool for logs. This is complete for the tool's complexity.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds meaningful extra guidance beyond the schema: it warns never to strip the ?token= suffix from session_id, explicitly states session_id comes from convoopen, and points to tfruns for discovering job_id values. This elevates understanding of 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 it checks Terraform deployment job status and explicitly distinguishes from siblings: 'Use tflogs to stream the actual deployment logs' and mentions tfruns for discovering job IDs. The verb 'check' and resource 'Terraform deployment' are specific, 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?

It provides explicit when-to-use guidance ('Use this tool to quickly check if a deployment is running, completed, or failed'), exclusions ('without streaming logs' -> use tflogs), and prerequisites (REQUIRES session_id, OPTIONAL job_id with tfruns reference). This fully informs agent selection among siblings.

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