InsideOut (Riley)

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

Annotations readOnlyHint=true and openWorldHint=true are consistent. The description adds that the tool fetches temporary read-only credentials securely and queries the AWS API directly. It explains response tiers (summary, detail, raw) and that it works even after failed deploys. 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 lengthy but well-structured with sections (PREREQUISITE, RESPONSE TIERS, REQUIRES, supported services, METRICS, BILLING, EXAMPLES). It is front-loaded with key information. Some redundancy could be trimmed (e.g., 'Inspection: Inspect AWS infrastructure' repeats), 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?

Given the tool's complexity (6 parameters, many services/actions, response tiers, prerequisites), the description is thorough. It covers prerequisites, how to use metrics and billing, and provides multiple examples. Without an output schema, it still explains response tiers (summary, detail, raw) 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?

The input schema has 0% description coverage, so the description compensates. It explains session_id format (sess_v2_ from convoopen), lists supported services, describes action with examples, explains filters as JSON string with examples, and clarifies detail and raw booleans for response tiers. This provides rich 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 the tool's purpose: 'Inspect AWS infrastructure for a deployed project.' It specifies the prerequisite of a prior deployment attempt, and distinguishes itself from sibling tools like convostatus (checks deployment attempt status) and tfdeploy (deployments). The verb 'Inspect' and resource 'AWS infrastructure' are 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 explicitly states when to use: 'Use this tool when the user asks about the status or details of their deployed infrastructure.' It details the prerequisite: requires a prior deployment attempt and advises checking convostatus for hasDeployAttempt=true. It also provides examples for various actions, offering clear 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds significant context: budgets, timeouts, concurrency cap, response cap, partial failure expectation, credential handling, and response structure. This fully informs the agent of behavioral traits.

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 headings (BUDGETS, PARTIAL FAILURE, etc.) and front-loaded with purpose and prerequisite. Every sentence adds value—no redundancy or 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 tool's complexity (batch, multiple limits, partial failure) and no output schema, the description covers prereqs, limits, response format, alternative tools, and examples. It is fully adequate 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 coverage is 0%, so the description carries the burden. It explains the session_id format and the subs array structure (service, action, optional filters) with examples. The filters parameter format is implied via JSON examples but not explicitly described. Still, agents can infer usage from examples and the supported services 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 it performs batch inspection of AWS infrastructure using up to 32 probes. It explicitly distinguishes from the sibling tool 'awsinspect' by noting that this is for batches and faster when checking more than ~3 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 ('Use this when you need to check more than ~3 resources') and when-not-to-use ('For a specific service's actions, use awsinspect (singular)'). Also specifies prerequisite (check convostatus for hasDeployAttempt=true) and required session_id format.

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 (readOnlyHint, openWorldHint) are complemented by the description, which adds details on required session_id, optional message_id and timeout, and return format. Does not contradict 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?

Description is concise and well-structured: front-loaded purpose, then usage, then parameter details. No redundant 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?

Covers when to use, required/optional parameters, constraints, and return format (same as convoreply). Highly complete for a waiting tool with no 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?

Despite 0% schema description coverage, the description explains each parameter: session_id from convoopen, message_id from timeout error, timeout integer with default 50 and max 55. This adds significant 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 the tool waits for a pending response after a convoreply timeout. It specifies the verb 'wait' and resource 'pending response', and distinguishes from sibling tools like convoreply.

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

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

Explicitly says 'USE THIS TOOL WHEN: convoreply returned a timeout error', providing clear context and conditions. Could mention when not to use, but the guidance is sufficient.

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

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

Annotations already provide readOnlyHint and openWorldHint. The description reinforces read-only behavior and adds details about the returned data (full message history, metadata). 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?

Concise with clear sections (INSPECTION, Returns, companion tools, use case, Requires). Every sentence adds value; no fluff.

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

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

For a tool with one parameter and no output schema, the description fully explains purpose, return data, usage context, and parameter format, making it 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 single parameter session_id is not described in the schema (0% coverage), but the description adds format requirement 'sess_v2_...', which is essential for correct invocation.

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 inspects a session's conversation transcript and metadata, using specific verbs ('view', 'returns') and distinguishing itself from sibling tools like convostatus, tfruns, and stackversions.

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 provides when-to-use scenarios ('what did I say earlier?', retracing session state) and lists companion tools for different purposes, along with a read-only note.

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 explains that the tool returns a session_id required for subsequent calls, that the response contains a message from the advisor Riley, and includes critical instructions like not answering on behalf of the user. It also details parameter behavior like auto-detecting source. This goes far beyond the minimal 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 lengthy but well-structured with clear sections (WORKFLOW, CRITICAL, IMPORTANT, TIP) and bullet points. Every sentence provides essential information for correct usage, though it could be slightly more 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 the tool's role as the first step in a complex workflow, the description covers: purpose, return value (session_id, Riley's message), parameter details, usage triggers, and workflow coupling. It also references additional context in 'workflow.usage' prompt, making it thorough for an AI 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?

The input schema has 0% description coverage, but the tool description fully compensates by explaining each parameter: source (with examples of tool names), project_context (what to include/exclude, example), and github_username (purpose). This adds significant value 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 explicitly states that this tool starts an infrastructure design conversation by opening an InsideOut V2 session and receiving an intro message. It clearly names the specific verb 'open' and resource 'session,' and distinguishes it from sibling tools like 'convoreply' by noting it is step 1 of a 4-step workflow.

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

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

The description provides explicit trigger keywords such as 'setup my cloud infra' and 'start insideout,' and indicates this is the initial step in a workflow. While it does not list when not to use the tool, it gives clear context for when to start the 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?

Annotations already declare openWorldHint and destructiveHint. The description adds significant behavioral context: it is a step in a workflow, returns assistant reply with signals, and warns against fabricating user answers. 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 well-structured with clear sections (WORKFLOW, CRITICAL, etc.) and front-loads important information. While lengthy, every part adds necessary context for correct tool usage. Could be slightly trimmed but remains effective.

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

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

Given the tool's complexity (6 parameters, no output schema, multi-step workflow), the description is highly complete. It covers return signals, workflow phases, relationships with sibling tools, and edge cases like when to call other tools.

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 0%, so description carries full burden. It explains most parameters: session_id, timeout, project_context, auto_accept, and text (implied). However, the 'retry' parameter is not mentioned at all, which is a minor gap.

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: sending a user message to an active InsideOut session and receiving the assistant reply. It also distinguishes itself from sibling tools like convoopen (session start) and convostatus (progress check).

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 and when-not-to-use instructions: do not answer Riley's questions, forward them to the user. Specifies workflow phases and when to call tfgenerate. Notes requirement of session_id from convoopen and gives guidance on optional parameters like project_context and auto_accept.

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. Description goes beyond by detailing the four sections of output (Components, Config, Pricing, Phase Indicators) and their contents, effectively explaining behavior even without an output 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?

Well-structured with bullet points and clear sections. Front-loaded with purpose and usage guidance. Slightly verbose in listing detailed bullet items, but every sentence adds value relative to complexity.

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 lacking an output schema, the description provides a comprehensive breakdown of the return structure (Components, Config, Pricing, Phase Indicators) and their meanings. Also specifies prerequisite and use cases, making the tool self-contained.

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

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

Schema has 0% description coverage. Description only adds meaning for session_id (source/format) but completely omits include_code, leaving its purpose unclear. Insufficient compensation for undocumented 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?

Clearly states 'View the current infrastructure stack for a session' with detailed breakdown of components, config, pricing, and phase indicators. Differentiates from siblings like awsinspect or convoinspect by focusing on session stack status.

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

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

Explicitly lists example user queries that should trigger this tool, and mentions prerequisite (session_id from convoopen). Does not explicitly state when not to use or list alternatives, which prevents 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 already declare idempotentHint=true and destructiveHint=false. The description adds that the tool polls, requires user interaction, and handles credentials securely. It does not contradict annotations, and additional context (polling, user action) enhances transparency 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 emojis, bold headers, and numbered steps, making it scannable. It front-loads the purpose and use case. Slightly verbose but earns each sentence; could trim minor redundancy (e.g., 'This secure connection allows...' is useful but a bit lengthy).

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 (polls external user action, multiple steps, no output schema), the description covers the workflow, prerequisites, and expected user flow. It lacks explicit mention of timeout behavior or return value, but the agent can infer success/failure from credential existence. Overall sufficiently 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 has 0% description coverage, yet the description explains all three parameters: session_id (required, format), cloud (optional, 'aws' or 'gcp'), timeout (integer, default 300, max 600). This fully compensates for missing schema descriptions and adds crucial usage context like default and max values.

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

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

The description clearly states the tool waits for cloud credentials to be connected, specifies the verb 'wait', and distinguishes it from siblings like tfdeploy and convoawait by detailing the exact use case (after auth_required errors). It uses specific resource 'cloud credentials' and 'Luther Systems subscription'.

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

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

Explicitly states when to use (after tfdeploy returns specific errors), provides a numbered workflow, and includes a strong 'do not call without showing URL' warning. Also references the required prerequisite (session_id from convoopen) and optional parameters.

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 indicate readOnlyHint and openWorldHint, but the description adds critical behavioral details: secure credential fetching, direct GCP API queries, response tiers (summary, detail, raw), and required IAM roles. No contradiction.

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

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

The description is lengthy but well-structured with clear sections, front-loading the purpose and prerequisites. While dense, every part adds value, though it could be slightly more 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?

With 6 parameters, no output schema, and high complexity, the description covers prerequisites, response tiers, supported services, metrics, billing, IAM roles, and examples. It is exceptionally complete for guiding correct tool 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 has 0% description coverage, but the description fully explains all parameters: session_id format, service list, action possibilities, filters JSON format, and detail/raw booleans. This compensates fully for the schema gap.

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 inspects GCP infrastructure after a deployment attempt, distinguishing it from sibling tools like awsinspect and tfstatus. The specific verb 'inspect' and resource 'GCP infrastructure' make 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 clear prerequisites (prior deployment attempt), references convostatus to check hasDeployAttempt, and gives examples. While it doesn't explicitly state when not to use, the conditions are well outlined.

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 include readOnlyHint=true and openWorldHint=true. The description adds extensive behavioral details: timeout limits (30s per-sub, 60s total), concurrency cap 8, 512KB response cap with truncated fields, credential fetching behavior, and summarized responses. No contradictions 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 lengthy but well-structured with sections (BATCH INSPECTION, PREREQUISITE, BUDGETS, EXAMPLES). It is front-loaded with key information. However, some redundancy exists (e.g., repeating concurrency limits in both narrative and bullet list). Still, the structure aids readability 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?

Given the tool's complexity (batch operations, partial failure, credential optimization, no output schema), the description is comprehensive. It covers all critical aspects: prerequisite, usage guidance, performance benefits, limits, failure modes, response structure, and examples. No gaps identified.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining the 'subs' array structure (service, action, optional filters), listing supported services, and providing examples. It clarifies that filters are optional and can be used for metrics with time ranges.

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

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

The description clearly states that this is a batch inspection tool for GCP, supporting up to 32 probes per call, and distinguishes it from the singular gcpinspect by noting it is faster for multiple resources. It uses specific verbs like 'run up to 32 GCP inspect probes' and explicitly says 'Use this when you need to check more than ~3 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 guidance on when to use: 'Use this when you need to check more than ~3 resources.' Also states prerequisites (deploy attempt required), notes partial failure is expected, and warns against using it for action discovery (use gcpinspect singular).

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

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

Discloses that responses include hints with next_actions and related_tools, adding value beyond readOnlyHint and openWorldHint 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?

Concise 4-sentence description, front-loaded with purpose, efficiently covering usage and output.

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?

Complete for a help tool with no output schema: covers invocation, sections, and response hints.

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?

Lists valid sections (workflow, tools, examples, inspect) for the 'section' parameter, which is not described in the input schema (0% 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?

States specific verb 'Get workflow guidance' for infrastructure tools, distinguishes from sibling tools which are specific operational 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?

Describes when to call help() vs help(section=...), providing clear usage context without 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds no additional behavioral context (e.g., no mention of rate limits or auth beyond session_id). The description is consistent with annotations and adds minimal transparency value.

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

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

Description is front-loaded with the core purpose, uses bullet points for key details, and every sentence is necessary. No filler words.

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

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

Given the tool's simplicity (3 params, no output schema), the description adequately covers inputs and behavior. It mentions the diff output format (component-level, field-level, pricing deltas), though an explicit return type or structure would be helpful. No output schema exists, so the description partially fills the 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 has 0% description coverage, but description explains the default behaviors (from_version defaults to latest applied, to_version defaults to current draft) and the required session_id format (sess_v2_...). This adds meaningful context 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?

Description clearly states it provides a structured diff between two stack versions, showing component-level changes, field details, and pricing deltas. This verb+resource is distinct from siblings like stackversions (just lists) or tfplan (plan vs. diff).

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

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

Specifies default values for optional parameters (from_version defaults to latest applied, to_version defaults to current draft) and notes that session_id must be in 'sess_v2_...' format from convoopen. However, no explicit guidance on when to use this tool versus alternatives like stackrollback or tfdrift.

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 indicate idempotent and non-destructive behavior. The description adds that it creates a draft (not immediate effect) and updates in-place, providing useful behavioral context 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?

Three short paragraphs: purpose, behavior, prerequisites. All sentences are necessary and front-loaded. No fluff.

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

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

Covers behavior and prerequisites well. Lacks explicit mention of return value or confirmation, but given the lack of output schema, the description is reasonably complete for an agent to infer the outcome.

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

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

With 0% schema description coverage, the description compensates by explaining 'version' is a target version number and 'session_id' is from convoopen with format sess_v2_..., giving essential 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 the tool's purpose: creating a draft version by reverting to a previous version's config, specifying what is copied and the single-draft rule. This is distinct from sibling tools like stackdiff and stackversions.

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 guidance: 'Use stackversions first to find available version numbers' and 'REQUIRES: session_id from convoopen response.' This directs the user to prerequisites, though it doesn't explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true. Description adds sorting (newest first) and what fields are shown, but does not disclose pagination or rate limits. Does not contradict 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?

Four sentences, front-loaded purpose, no fluff. Requirements are clearly separated. Efficient and well-structured.

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

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

For a simple list tool with one required param and no output schema, the description covers purpose, usage, and output format. Minor omission: no mention of pagination if results are large, but generally 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?

With 0% schema description coverage, description adds meaning: it specifies the parameter must be a session_id from convoopen, format sess_v2_..., and is required. This compensates for the lack of 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 states it lists all stack versions for a session, newest first, and specifies the data shown (version number, status, change summaries, timestamps). This clearly distinguishes it from sibling tools like stackdiff or stackrollback.

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

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

It gives explicit use cases: see design history, review changes, find version to roll back to. Also states the required session_id format and source. Does not explicitly mention when not to use, but the context is clear.

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

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

The description adds detail about the initiator field and categories but does not reveal behavioral traits beyond what annotations already provide (openWorldHint and destructiveHint). It is consistent with annotations but adds limited extra 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 well-structured with headings, bullet points, and examples. It is concise enough for a tool with 7 parameters, though slightly longer than minimal.

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 simplicity of a feedback submission tool, the description covers all necessary aspects: required and optional parameters, categories, examples, and usage details. No output schema exists, but the description is self-sufficient.

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

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

Schema description coverage is 0%, but the description compensates by listing all parameters, their optionality, and explaining categories and the initiator field. This adds significant 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 the tool submits feedback, bug reports, or feature requests to Luther Systems. It uses a specific verb-resource combination and is distinct from sibling tools (infrastructure and conversation 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 explains when to use the tool (for user feedback, bug reports, feature requests, etc.), provides examples, and notes agent-initiated usage. It does not explicitly state when not to use, but the context is clear.

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

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

The description discloses critical behavioral traits not covered by annotations: long-running job (15+ min), single-flight constraint (only one job per session), returns tf_job_conflict on conflict, and credential re-auth flow. Annotations indicate destructiveHint=true (deployment modifies infrastructure) and openWorldHint=true (external cloud resources), which the description aligns with, so no contradiction.

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 headings ('WORKFLOW', 'IMPORTANT', 'SINGLE-FLIGHT', 'OPTIONAL', 'CREDENTIAL FLOW') and bullet points, making it scannable. It front-loads the purpose and workflow position. While it is somewhat lengthy (approximately 300 words), every sentence serves a purpose, and the length is justified by the complexity of the tool.

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

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

Given the tool's complexity (long-running, single-flight, credential flow, optional params, no output schema), the description is comprehensive. It covers the main purpose, prerequisites, parameter explanations, error handling (conflict scenario), workflow integration (tfplan->tfdeploy->tfstatus), and credential re-auth steps. No output schema exists, so the description compensates fully with context about what the tool returns (confirmation with job_id or conflict).

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%, so the description must compensate. It explains most parameters: session_id (required), plan_id (apply a plan), sandbox (testing flag), ignore_drift (bypass drift check), force_new (override single-flight). However, 'version' and 'project_id' are not described, leaving a gap. Overall, the description adds substantial meaning beyond the schema for 5 of 7 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 clearly states this is Step 4 of 4, deploying infrastructure by starting a Terraform job. It specifies the action ('deploy infrastructure') and distinguishes from sibling tools like tfplan (planning), tfdestroy (destroy), and tfstatus (monitoring) by positioning it as the deployment step after file generation.

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 (Step 4, after Terraform files generated), when-not-to-use (if another TF job is in flight, use tfstatus/tflogs instead unless force_new=true), and alternative tools (tfplan for preview, tfdestroy for teardown). It also covers prerequisites (session_id) and a detailed credential flow with connect_url and credawait.

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 indicate destructive and open-world hints. The description adds critical behavioral details: long-running job, single-flight mechanism, conflict return with job_id, force_new override, and that hasDeployment becomes false after completion. 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 structured with clear sections (DESTROY, IMPORTANT, SINGLE-FLIGHT, etc.) and front-loads key information. While slightly verbose, it is organized and each sentence serves a purpose.

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

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

Given the tool's two parameters and no output schema, the description covers purpose, prerequisites, behavioral traits, error conditions, and post-destroy state. It is sufficiently 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?

Input schema has 0% description coverage. The description explains session_id format and source, and force_new's purpose (bypass single-flight guard for wedged jobs) and default (false). This adds significant 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 the verb 'Destroy' and the resource 'infrastructure', specifying it tears down previously deployed infrastructure via an Oracle destroy endpoint. It is distinct from sibling tools like tfdeploy, tfplan, etc.

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 context: after a successful deployment. It lists prerequisites (session_id from convoopen, prior successful deployment), warns about long-running jobs and single-flight, and mentions alternatives for monitoring (tfstatus/tflogs) and overriding (force_new). It also describes post-destroy state.

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 beyond annotations by detailing the read-only nature, return value (job_id), single-flight limitation, conflict response format, and the force_new override. 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 well-structured with headings and bullet points, and the key info is front-loaded. However, it is somewhat verbose with extra details that could be trimmed without losing clarity.

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

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

Given no output schema, the description covers inputs, prerequisites, behavior (single-flight), error handling, and next steps. It is complete for the tool's complexity.

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

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

With 0% schema description coverage, the description compensates fully. It specifies that session_id must be in the format 'sess_v2_...' from convoopen, and explains force_new's purpose and when to use it.

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

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

The description clearly states the tool's purpose: 'Run a read-only drift detection check' to detect infrastructure drift. It distinguishes itself from siblings like tfdeploy and tfplan by explicitly mentioning it is read-only and providing context for when to use 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 provides explicit guidance on when to use this tool vs alternatives, including prerequisites (session_id, prior deployment), single-flight constraint, and how to handle conflicts. It also directs users to tflogs for results and mentions using tfdeploy with ignore_drift when drift is detected.

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 beyond annotations (idempotentHint, destructiveHint, openWorldHint) by detailing the default summary+download URL response, the include_code fallback, the critical workflow steps (ask user for directory, wait for confirmation), and error messages for precondition failures. 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-structured with bold headings, bullet points, and emojis. Information is front-loaded with purpose and workflow step. Every sentence adds value; no redundancy. Despite length, it remains concise for the complexity.

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 role in a multi-step workflow, the description covers prerequisites (session_id, terraform_ready state), default and fallback responses, post-action steps (ask user for save location, deploy with tfdeploy), and error handling. No output schema is provided, but the response type is adequately described.

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

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

With 0% schema description coverage, the description compensates by explaining the required session_id format (sess_v2_...) and the optional include_code parameter's purpose (fallback for curl failures). While not exhaustive (no value constraints), it adds meaningful 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 that the tool generates Terraform files from a completed InsideOut session, with specific verb 'Generate' and resource 'Terraform files'. It distinguishes itself from siblings like tfdeploy (deployment) and convoreply (conversation) by placing it as step 3 of a 4-step workflow.

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

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

The description explicitly states the prerequisite (call only after convoreply returns terraform_ready=true), and gives clear when-to-use conditions (user asks for 'see the terraforms' or similar). It also provides a fallback for curl/unzip failures.

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 and openWorldHint, and the description adds rich behavioral details: different mechanisms for completed vs running jobs, pagination with last_event_id, SSE streaming, timeout limits, and context window warning. 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 organized into clear sections (general, pagination steps, response fields, requirements, context warning). Each sentence adds value, though slightly lengthy; front-loading the purpose helps.

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 details response fields (logs, last_event_id, complete, total_logs). It covers pagination thoroughly, context window concerns, and required inputs. Nothing critical is missing for an agent to use 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?

Schema coverage is 0%, but the description fully explains every parameter: session_id required, job_id optional, timeout with defaults, last_event_id for pagination, and tail for truncation. It also provides usage patterns for pagination.

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 'MONITORING: Fetch Terraform deployment logs with pagination' and distinguishes between running and completed jobs. Among siblings like tfstatus and tfruns, this is the specific logs tool, so 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 explains prerequisites (session_id from convoopen), optional parameters, and context warnings. It implicitly tells when to use (monitoring deployments) but lacks explicit when-not-to-use or direct sibling comparisons.

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

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

Annotations include readOnlyHint=true and openWorldHint=true. The description adds that sensitive outputs are redacted and that outputs are structured values. This provides additional context beyond annotations without contradiction.

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 bold header, inline examples, and bullet-like format for requirements/options. While slightly verbose, it is efficient and front-loaded with purpose.

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

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

Despite having no output schema, the description covers default behavior, optional parameters, redaction, and expected return types. It fully compensates for schema gaps and provides comprehensive guidance.

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%, but the description explains each parameter: session_id format and source, job_id for specific deploy, and lifecycle with an example. This adds significant 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 states 'INSPECTION: Retrieve Terraform outputs from a completed deployment' and lists example outputs (VPC IDs, endpoints). This distinguishes it from sibling tools like tfplan, tflogs, and 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?

It explains that by default it returns outputs for the latest successful deploy, and optionally allows specifying a job_id for a specific deployment. It also notes required session_id format, but does not explicitly exclude alternative tools.

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

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

Annotations indicate idempotent and non-destructive, which description reinforces by stating no changes applied. Discloses single-flight behavior, optional force_new override, and credential handling. 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?

Well-structured with clear sections (PREVIEW, SINGLE-FLIGHT, REQUIRES, OPTIONAL). Concise yet comprehensive, no redundant sentences. Front-loaded with key purpose.

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

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

Covers all necessary context: return values (job_id, plan_id, project_id), error handling (tf_job_conflict), how to get output (tflogs), and prerequisites (session_id format). Adequate given no 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?

With 0% schema coverage, description compensates well by explaining each parameter: session_id required with format hint, sandbox (default false, testing vs real), force_new (overrides guard). Minor lack of explicit default values, but context is clear.

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 runs terraform plan to preview infrastructure changes without applying. It distinguishes from sibling tools like tfdeploy (apply) and tfdestroy, and specifies the preview nature upfront with 'PREVIEW' labeling.

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

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

Explicitly states when to use (preview before applying), when not (use tfdeploy instead), and provides alternatives (tflogs to stream output). Also covers single-flight rule and how to handle conflicts with 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?

Discloses read-only inspection behavior, which aligns with annotations (readOnlyHint, openWorldHint). Adds specifics on returned data fields. Does not address potential edge cases like empty history or rate limits, but the tool is simple.

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?

Efficient single paragraph with front-loaded 'INSPECTION' label. Each sentence adds value: purpose, output, use cases, parameter requirement. 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 tool with 1 parameter and no output schema, the description adequately covers what it does, what it returns, and how to provide the parameter. No missing information needed 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?

Adds critical meaning: specifies the session_id format (sess_v2_...) and its source (convoopen response). Since schema coverage is 0%, this provides necessary guidance for correct parameter use.

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 lists all Terraform deployment runs for a session, specifying the returned fields (job IDs, statuses, types, timestamps). This distinguishes it from sibling tools like tfstatus (current state) or tfplan (pending changes).

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 lists use cases: viewing history, finding job IDs, checking success/failure. Also notes the required session_id format. However, it lacks explicit guidance on when not to use it or mention alternatives among 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?

Annotations declare readOnlyHint and openWorldHint. The description adds detailed behavioral context: it does not stream logs, explains liveness timestamps (updated_at vs last_refresh_at) and what they indicate, and notes that last_refresh_at is absent on unrefreshed rows. 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 moderately long but well-structured: a header, then purpose, usage, requirements, and detailed timestamp behavior. Every sentence serves a purpose, though the timestamp section could be slightly tighter. Still, it's efficient for a tool with behavioral nuance.

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 absence of an output schema, the description covers purpose, usage, parameters, and behavioral details (timestamps, no log streaming). It does not list every possible return field but mentions 'job status, job_id, and other metadata', which is sufficient for most use cases. The tip to examine workflow.usage adds completeness.

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

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

Input schema has 0% description coverage, so description must compensate. It does: explains that session_id is required and must be in format sess_v2_..., and job_id is optional with guidance to use tfruns to discover IDs. This adds clear 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 starts with 'MONITORING: Quick status check for Terraform deployments' and clearly states 'Check the current status of a Terraform deployment job.' It distinguishes itself from the sibling tool 'tflogs' by noting it returns only status and metadata without streaming logs.

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

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

Explicitly states when to use this tool ('quickly check if a deployment is running, completed, or failed') and when not ('Use tflogs to stream the actual deployment logs'). Also provides required session_id and optional job_id sourcing.

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