InsideOut (Riley)

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

Annotations already indicate read-only (readOnlyHint=true). Description adds credential mechanism, API query, response tiers, and specific actions for metrics/billing. Does not mention rate limits or errors, but general behavior is well-covered.

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

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

Well-structured with sections, examples, and key info front-loaded. Slightly long but every sentence adds value. IAM permissions for cost explorer are specific but useful.

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

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

Despite no output schema, description covers response tiers, prerequisites, supported services, parameter formats, and edge cases (failed deploys, orphaned resources). Comprehensive for agent use.

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

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

With 0% schema coverage, description fully explains all 6 parameters: session_id (format and source), service (full supported list), action (examples), filters (JSON examples for metrics/billing), detail and raw (tier boolean meanings). Also provides examples.

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?

Clear verb 'inspect' and resource 'AWS infrastructure'. Explicitly distinguishes from siblings like gcpinspect and awsinspect_batch. States it's for deployed projects after deployment attempt.

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 (user asks about deployed infrastructure status/details) and prerequisite (prior deployment attempt, check convostatus). Details response tier usage for different needs. No exclusion but context 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 indicate read-only and open-world hints. The description adds significant behavioral context: partial failure is expected, credential failure behavior, budget limits (concurrency cap of 8, timeouts, response cap of 512 KB), and the response format. This complements annotations with actionable details.

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 thorough and well-organized with headings and bullet points, but slightly verbose. Every section adds value, but some details (e.g., full list of supported services) could be streamlined. Still, it is effectively structured and front-loaded with key prerequisites.

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

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

Given the tool's complexity and lack of output schema, the description covers all essential aspects: prerequisite, usage context, budgets, failure modes, input requirements, supported services, and examples. It leaves no obvious gaps for an agent to understand 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?

The input schema has 0% description coverage, but the description compensates fully. It explains the session_id format (sess_v2_...), lists supported services, and provides examples of the subs array structure. This adds crucial meaning beyond the bare 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: running up to 32 AWS inspect probes in one call. It specifies the scope (batch inspection of multiple resources) and distinguishes itself from the sibling tool 'awsinspect' by noting that batch is for checking >3 resources and is not for discovery.

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 the tool (when checking more than ~3 resources) and when not to (for service discovery, use awsinspect). It also lists prerequisites (deploy attempt required, check convostatus for hasDeployAttempt=true) and includes budgets and partial failure handling.

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, indicating no mutation and external interaction. Description adds waiting behavior, timeout max, and return format matching convoreply. However, it doesn't specify what happens on timeout expiration (e.g., 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?

Description is well-structured: succinct first sentence, then usage callout, then bullet points for params. No fluff, all sentences add 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?

Covers main scenario and return format (same as convoreply). Lacks error handling details (e.g., timeout reached, invalid session) but given simplicity and sibling context, it is mostly 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 zero description coverage, but description fully compensates: session_id from convoopen, message_id from convoreply timeout error, timeout with default 50 and max 55. This adds essential meaning beyond type/null constraints.

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 waits for a pending response after a convoreply timeout. It specifies the verb 'Wait for' and resource 'pending response from Riley', distinguishing it from siblings like convoreply (which initiates) and convoinspect (which inspects).

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

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

Explicitly tells when to use: 'USE THIS TOOL WHEN: convoreply returned a timeout error'. It also explains it continues waiting without resending, giving clear context for its 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?

Reinforces readOnlyHint annotation with 'Read-only; never mutates session state.' Adds behavioral constraint on session_id format (sess_v2_...) beyond what schema provides. 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?

Well-structured with header, bullet list, usage note, and requirement. Slightly verbose but each sentence adds value. Front-loaded with main 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?

Comprehensively covers what the tool returns (transcript and metadata) and how it relates to siblings. No output schema, but description sufficiently describes results. All relevant context is present.

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

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

Schema has 0% description coverage for the sole parameter session_id. Description adds format requirement (sess_v2_...) and states it is required, adding 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?

Explicitly states 'INSPECTION: View a session's conversation transcript and metadata' and lists returned data (full message history, session meta). Clearly distinguishes from siblings like convostatus, tfruns, stackversions by describing their complementary roles.

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

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

Provides explicit usage scenarios ('what did I say earlier?' or retracing session state), declares read-only nature, and lists sibling tools with their purposes for alternative use cases.

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 fully reveals behavioral traits: it returns a session_id and an intro message, warns that Riley asks questions which must be forwarded to the user, and provides critical usage instructions. Annotations (openWorldHint, destructiveHint) add no contradiction; description goes far beyond.

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, warnings, and tips. Every sentence adds value; minor redundancy could be trimmed, 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 role in a multi-step workflow, the description fully covers: the response content, parameter semantics, required next steps (session_id usage), and behavior expectations. No output schema is mentioned, but the response structure is clearly 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?

Despite 0% schema coverage, the description thoroughly explains each parameter: source (auto-detect IDE), project_context (tech stack summary, never secrets), and github_username (optional for attribution). It adds constraints and examples, making up for the missing 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 it is 'Step 1 of 4 - Start infrastructure design conversation' and 'Open an InsideOut V2 session'. It distinguishes from sibling tools by specifying the workflow and the need to capture session_id for subsequent calls like convoreply, tfgenerate, 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 explicitly lists trigger keywords for when to use this tool (e.g., 'setup my cloud infra', 'provision infrastructure'). It provides context as the first step in a workflow, but does not explicitly list 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?

The description discloses key behaviors: it sends a user message and waits for a response, the response contains a clean message to display, and response signals indicate next workflow steps. This adds value beyond annotations (openWorldHint, destructiveHint) 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 lengthy but well-structured with headings and bullet points. It front-loads the workflow step and main purpose, and each section adds necessary detail. A small reduction in verbosity could improve conciseness.

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 (multiple parameters, sibling tools, workflow dependencies), the description is thorough. It covers when to use, how to handle responses, parameter usage, integration signals, and provides a tip for checking progress via convostatus. All critical aspects are addressed.

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

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

With 0% schema description coverage, the description compensates by explaining session_id, text (implied), timeout (max 55), project_context (only new details), and auto_accept (default true). However, the 'retry' parameter is not mentioned, leaving 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: 'Send a user message to the active InsideOut session and receive the assistant reply.' It positions it as Step 2 of a 4-step workflow, distinguishing it from siblings like convoopen and convostatus.

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 extensive guidance: it must be used after convoopen, before tfgenerate; warns against answering Riley's questions; explains when to call other tools based on response signals (e.g., [TERRAFORM_READY: true]); and details appropriate use of 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 include readOnlyHint: true and openWorldHint: true, and the description confirms a read-only inspection role with 'INSPECTION' and 'Returns the current state'. It adds behavioral context by listing the required session_id format and the tool's purpose, fully aligning with 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 clear headline, bullet points, and logical sections. It is concise yet comprehensive, with no redundant sentences. The front-loaded 'INSPECTION' label immediately signals the tool's nature.

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

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

For an inspection tool with no output schema, the description adequately explains returned data (components, config, pricing, phase). It includes prerequisites (session_id) and usage examples. However, it fails to document the include_code parameter, leaving a completeness 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?

With 0% schema coverage, the description must compensate. It explains session_id semantics (required, format from convoopen) but completely omits the include_code parameter, leaving its purpose unclear. This significant gap lowers the score.

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 as 'INSPECTION: View the current infrastructure stack for a session' and details the specific categories (Components, Config, Pricing, Phase Indicators) returned. This distinguishes it from sibling tools like awsinspect or convoinspect which likely inspect different scopes.

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 lists example user queries that trigger this tool ('what is my current stack?', 'show my infrastructure') and mentions the required session_id from convoopen. However, it does not clarify when NOT to use it or compare to alternatives like convoinspect.

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 cover safety (non-destructive, idempotent). Description adds polling behavior, parameter constraints (timeout max), and secure credential handling. Doesn't detail timeout behavior, but adequate.

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

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

Well-structured with bold headings, bullet points, and a clear workflow. Slightly verbose but effective. Front-loaded with key use-case.

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

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

Comprehensive for a polling tool: covers prerequisites, workflow, parameter details, and security context. No output schema but not needed.

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 fully explains each parameter: session_id is required and format (sess_v2_...), cloud is optional with values 'aws' or 'gcp', timeout is integer seconds with defaults and max.

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: to wait for cloud credentials to appear after user connects account. It distinguishes from sibling tools by specifying it is for polling credentials after tfdeploy errors.

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 errors like 'auth_required'), and includes a workflow with a required precondition (show URL to user first). No ambiguity.

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?

While annotations already indicate readOnlyHint and openWorldHint, the description adds substantial behavioral information: it fetches temporary read-only credentials, queries GCP API directly, works after failed deploys, lists required IAM roles, and details response tiers (summary/detail/raw) with token efficiency considerations. 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 clear sections (prerequisites, response tiers, supported services, examples). Every sentence adds value, though some redundancy exists (e.g., purpose repeated). The front-loading of the purpose and prerequisite is effective.

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

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

The tool has no output schema, but the description covers response tiers, IAM roles, supported services, actions, metrics, billing, and prerequisites. It provides comprehensive guidance for an agent to use 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 0%, but the description compensates fully by explaining each parameter: session_id format and source, service list, action examples, filters as JSON with examples, detail and raw booleans with tier definitions. Examples further clarify 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 'Inspect GCP infrastructure for a deployed project' and elaborates on the tool's function. It distinguishes from siblings like gcpinspect_batch by focusing on synchronous inspection after deployment, and from awsinspect by targeting GCP.

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 mentions the prerequisite (prior deployment attempt), how to check it via convostatus, and when to use the tool (when user asks about deployed GCP infrastructure). It does not explicitly contrast with gcpinspect_batch, but the context cues are strong.

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?

Adds critical details beyond annotations: budgets (32 sub-probes, timeouts, concurrency cap, response cap with truncation), partial failure expectations, credential fetch behavior, and summarized response nature.

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 headings (BUDGETS, PARTIAL FAILURE, REQUIRES, EXAMPLES). Every sentence adds value, no redundancy. Efficient despite length due to density of useful 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?

Covers all essential context: prerequisites, response structure, error handling, performance benefits, and limits. Includes examples for different use cases. No output schema, but description adequately explains response format.

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, the description compensates by explaining session_id format, subs structure (service/action/filters), filters as JSON string, and supported services via examples. Slightly less explicit for individual parameters but still highly informative.

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 runs up to 32 GCP inspect probes in one call and distinguishes it from the singular gcpinspect for individual probes.

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 when to use (more than ~3 resources), provides prerequisites (check convostatus), and warns when not to use (not for listing actions, use singular gcpinspect for full metadata).

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, indicating a safe read operation. The description adds that responses include hints with next_actions and related_tools, providing useful 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 concise: three sentences total. It communicates purpose, usage variations, and expected response content without unnecessary 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 simple help tool, the description adequately explains the parameter usage and response content (hints with next_actions and related_tools). No output schema exists, but the description sufficiently covers what to expect. Given the complexity, it is mostly complete.

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

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

The input schema has one optional parameter 'section' with 0% description coverage. The description compensates by explaining that help() gives an overview and help(section=...) gives a detailed guide, listing the valid sections (workflow, tools, examples, inspect), effectively adding semantic 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 the tool provides workflow guidance for InsideOut infrastructure tools. It specifies calling with no arguments for an overview or with a section parameter for a detailed guide, listing the available sections (workflow, tools, examples, inspect). This distinguishes it from sibling tools that perform specific infrastructure actions.

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 to call help() for a compact overview or help(section=...) for a detailed guide, and lists the sections. However, it does not provide explicit guidance on when to use this tool versus sibling tools like awsinspect or tfplan, leaving that implicit.

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, so the description's claim of showing diffs aligns. It adds the required session_id format but does not elaborate on other behaviors like authentication or rate limits. Some 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?

Three sentences: purpose, output details, parameters with defaults. Front-loaded and no extraneous content. Every sentence earns its place.

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

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

For a diff tool, the description covers what it does, what it shows, parameter defaults, and a prerequisite. No output schema exists, but the description sufficiently describes the output. Could mention limitations but overall 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, the description compensates by explaining defaults for from_version and to_version and specifying the required format for session_id. This adds significant meaning beyond the schema's empty 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 'Structured diff between two stack versions' and lists what it shows (component-level, field-level changes, pricing deltas). It distinguishes itself from siblings like stackversions (list versions) and tfplan (plan changes) by focusing on diffing specific 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 explains optional parameters with defaults and explicitly requires 'session_id from convoopen response', providing clear context for when to use the tool. It does not explicitly contrast with siblings but sufficient context is given.

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

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

Description explains that it copies components, config, and pricing, and has a single-draft rule (updates if exists). Annotations (idempotentHint true, destructiveHint false) are consistent with this behavior, and the description adds useful 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?

The description is concise with three short paragraphs, front-loaded with purpose, and no wasted words. Each sentence adds value.

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

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

For a simple 2-parameter tool, the description covers the operation, behavior (single-draft rule), required context, and pre-requisite tool usage. It lacks mention of return value or error handling, but this is acceptable given the lack of 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 description coverage, the description compensates by explaining the format and source of session_id ('sess_v2_...') and that version is the target version number. Though brief, it provides essential context for correct 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 creates a draft version by reverting to a previous version's config. The verb 'revert' is specific, and the tool is distinct from siblings like stackversions (list versions) and stackdiff (compare stacks).

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 to use stackversions first to find version numbers and specifies the requirement for session_id from convoopen. Does not explicitly state when not to use, but the context 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 declare readOnlyHint=true, consistent with listing. The description adds key behavioral details: ordering (newest first), output fields, and a crucial requirement that session_id must come from convoopen response with format 'sess_v2_...'.

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 brief sentences plus a requirement line. Each sentence adds distinct value: what it does, what it shows, and when to use it. No redundancy.

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

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

Given the simple tool with one parameter and no output schema, the description covers purpose, usage, parameter requirement, and output fields. Missing pagination or limits, but adequate for a list tool.

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

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

Schema description coverage is 0%, but the description compensates by specifying the session_id parameter's source and format, adding semantic value 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 clearly states the tool lists all stack versions for a session, ordered newest first, and details the output fields (version number, status, change summaries, timestamps). It is distinct 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?

The description provides explicit use cases: 'see the design history, review what changed between iterations, or find a version number to roll back to.' It doesn't explicitly mention when not to use it, but the context of sibling tools helps differentiate.

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 openWorldHint=true (tool may have side effects beyond output) and destructiveHint=false (not destructive). The description supplements this by disclosing that feedback is sent to the team, requiring session_id, category, and message. It explains the initiator field and its semantics, providing 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?

The description is well-structured with sections (FEEDBACK, REQUIRES, OPTIONAL, Categories, initiator, Examples). It is slightly verbose but every sentence adds value, including examples that illustrate usage. It is front-loaded with purpose. Could be trimmed minimally but is effective.

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

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

Given the tool has 7 parameters (3 required), no output schema, and no schema descriptions, the description covers all necessary context: required/optional fields, valid categories, initiator semantics, and illustrative examples. It is complete for an agent to correctly select and 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?

Schema coverage is 0% (no descriptions in schema properties). The description compensates fully by listing required and optional parameters, explaining each (e.g., user_email for follow-up, source default 'mcp'), defining categories (bug_report, feature_request, etc.), and detailing the initiator field with examples. 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 the tool submits feedback, bug reports, or feature requests to Luther Systems. It uses specific verbs ('submit', 'forward') and identifies the resource ('feedback to Luther Systems team'). It distinguishes from sibling tools which focus on infrastructure inspect, conversations, and terraform operations.

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: for forwarding user feedback, bug reports, feature requests, questions, or general feedback. It also notes the agent can use it to report issues. It provides clear context for use cases but does not explicitly mention when not to use it or alternatives, which is acceptable given siblings are unrelated.

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 (destructiveHint, openWorldHint), the description discloses long-running nature (15+ min), single-flight constraint, conflict return behavior, credential requirement with connect_url, and drift 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 a workflow header, detailed parameter explanations, and a separate credential flow section. Every sentence adds value; no redundancy.

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

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

Extremely thorough covering workflow, conflict handling, credential flow, and drift behavior. Minor gap: missing descriptions for version and project_id parameters. Otherwise complete for a complex deployment 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?

With 0% schema description coverage, description explains key parameters (session_id, plan_id, sandbox, ignore_drift, force_new) including formats and defaults. However, version and project_id are not described, leaving a gap for those 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?

Description clearly states 'Deploy infrastructure by starting a Terraform job' and positions it as Step 4 of 4. It distinguishes from siblings like tfplan (planning) and tfdestroy (destroy) by specifying the deployment role.

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

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

Provides explicit workflow guidance (tfplan -> tflogs -> tfdeploy), when to use (after Terraform files generated), when not to use (single-flight conflict, recommends tfstatus/tflogs), and credential flow with credawait. Also explains optional params like plan_id, sandbox, ignore_drift.

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 fully discloses behavioral traits: long-running job, single-flight guard with conflict return, optional force_new override, session kept after destroy with hasDeployment set to false. Annotations already mark destructiveHint=true, but the description adds rich context 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 sections and a prominent 'DESTROY:' label. It is thorough but could be slightly more concise; however, every sentence adds value.

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

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

Given the tool's destructive nature and dependencies, the description covers preconditions (session with prior success), runtime behavior (long job, single-flight), monitoring instructions, and post-destroy state. No output schema exists, but return behavior (conflict or job start) is 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?

Schema coverage is 0%, so the description must compensate. It explains the session_id format (sess_v2_...) and the force_new parameter (boolean, default false, purpose to bypass single-flight guard). This adds significant meaning beyond the bare 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 tfdestroy destroys previously deployed infrastructure via the Oracle destroy endpoint. It uses a strong verb ('DESTROY') and distinguishes itself from sibling tools like tfdeploy (which deploys) and tfplan (which plans).

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 (after a successful deployment), the single-flight constraint (only one job per session at a time), and alternatives (use tfstatus/tflogs to monitor, use force_new only if wedged). It also lists prerequisites 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 already declare readOnly and idempotent, and the description adds significant behavioral details: single-flight constraint, conflict response with job_id, force_new usage, and that it returns a job_id. 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 well-structured with clear sections and bullet points. Every sentence adds value, covering purpose, behavioral notes, prerequisites, and parameter details without being 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?

Given no output schema, the description explains the return value (job_id) and how to stream results (tflogs). It covers all essential aspects: operation, preconditions, single-flight behavior, error scenarios, and post-check actions. 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?

Although schema description coverage is 0%, the description thoroughly explains both parameters: session_id (required, format from convoopen) and force_new (optional boolean with meaning and when to use). This compensates fully for the schema's lack of 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 'DRIFT CHECK: Run a read-only drift detection check' and explains it checks whether deployed infrastructure has drifted from expected Terraform state. It uses specific verb and resource, distinguishing it from siblings like tfdeploy, tfdestroy, 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?

Explicitly provides when to use (drift detection) and when not to (read-only, no modifications). It mentions prerequisites (session_id, prior deployment), alternatives (tflogs for streaming), and handling of single-flight conflicts. Also explains what to do if drift is detected (fix or use tfdeploy with ignore_drift=true).

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

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

Describes default vs fallback behavior (include_code), workflow steps, and prerequisite. Annotations already indicate idempotent and non-destructive; description adds context about return format (summary+URL) and fallback logic. 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 sections, emojis, bold. Every sentence adds value. Front-loaded with workflow step and prerequisite. Efficient despite thoroughness.

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 prerequisite, usage triggers, default response, fallback, full workflow steps, and post-generation actions. No output schema but describes return sufficiently. Complete for a complex multi-step 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?

Despite 0% schema coverage, description fully explains both parameters: session_id format and required, include_code as fallback. Adds meaning beyond schema by clarifying when to use include_code.

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: generating Terraform files from a completed InsideOut design, and positions it as step 3 of 4. It distinguishes from sibling tools like tfdeploy, tfplan, etc., by focusing on 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?

Provides explicit prerequisite: only call after convoreply returns with terraform_ready=true. Gives clear when-to-use and when-not-to instructions, and outlines the full workflow including asking user for save location. No ambiguity for the agent.

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

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

Discloses detailed behavioral traits beyond annotations: REST vs SSE endpoints, pagination mechanism, response fields, and timeout behavior. The readOnlyHint is consistent; the description adds context about potential large logs and server-side filtering, enhancing 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 sections (MONITORING, PAGINATION, RESPONSE FIELDS, REQUIRES, OPTIONAL, CONTEXT WARNING), is front-loaded with the core purpose, and uses bold for emphasis. Every sentence adds value without redundancy.

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

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

Comprehensive for a tool with no output schema: it details all response fields (logs, last_event_id, complete, total_logs), explains pagination, and warns about context window. It also links to sibling tools for session_id and job_id, covering typical usage scenarios.

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

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

Despite 0% schema coverage, the description thoroughly explains all five parameters: session_id (required), job_id, timeout, last_event_id, and tail. It provides defaults, limits, and usage context (e.g., tail for completed jobs), adding 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 it fetches Terraform deployment logs with specific verbs like 'Fetch', and distinguishes between completed and running jobs. It is not a tautology and differentiates from sibling tools like tfruns by focusing on log retrieval rather than run listing.

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: contrasts completed vs running jobs, details pagination steps with concrete examples, and gives context warning about using tail to avoid large context windows. It also references required parameters like session_id from convoopen, aiding appropriate selection.

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

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

Annotations already indicate readOnlyHint and openWorldHint. Description adds valuable context: sensitive outputs are redacted, returns structured values. 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?

Description is well-organized with labeled sections (INSPECTION, REQUIRES, OPTIONAL). Front-loaded purpose, then behavior, then parameters. No unnecessary words, each sentence adds value.

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

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

With no output schema, description explains return type (structured output values, redacted sensitive). Covers all parameters, default behavior, and prerequisites. Sufficient for an AI agent to understand and 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?

Input schema has 0% description coverage, so description compensates fully. Explains session_id format and source, job_id for specific deployment, and lifecycle filter with example ('cloud-provision'). All three parameters are clearly defined.

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 'Retrieve Terraform outputs from a completed deployment', specifying verb and resource. Includes examples of output types (VPC IDs, endpoints) and distinguishes from sibling tools like tfplan and tfdeploy by focusing on post-deployment 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?

Provides clear prerequisites (session_id from convoopen), default behavior (latest successful deploy), and optional parameters for specific deployment or lifecycle step. Does not explicitly state when not to use, but context makes it clear it's for inspection after a deploy.

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. Description adds useful behavioral details: no changes applied, returns job_id/plan_id/project_id, single-flight behavior with conflict handling, credential handling, and sandbox mode. While not all facets are exhaustively detailed (e.g., rate limits), it significantly augments 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?

Description is well-structured with bolded sections (PREVIEW, SINGLE-FLIGHT, REQUIRES, OPTIONAL) and front-loaded with main action. Slightly verbose but each sentence adds value. Could be trimmed for extreme conciseness.

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, description covers return values (job_id, plan_id, project_id) and integration with other tools (tflogs, tfdeploy). Also explains single-flight, sandbox, and credentials. For a moderately complex tool, the description is complete and actionable.

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, so description must compensate. It does so thoroughly: explains sandbox as 'cheap sandbox template (testing only)', force_new as bypass for wedged runs, and session_id as required from convoopen response. This adds essential meaning beyond the bare 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?

Starts with 'PREVIEW: Run terraform plan to preview infrastructure changes', clearly stating the verb and resource. Distinguishes from siblings like tfdeploy, tfdestroy, and tfgenerate by focusing on preview without application.

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 changes before committing. Provides instructions to use tflogs for streaming, and to apply with tfdeploy. Also explains single-flight constraints and when to use force_new, giving clear context about conflicts.

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 tool is safe. The description adds context by listing the types of data returned (job IDs, statuses, types, timestamps) and the required session_id format. 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?

Three sentences, each informative: first states purpose, second describes return data, third gives usage context and prerequisite. No filler.

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

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

For a simple list tool with one parameter and no output schema, the description covers input requirement, return fields, and use cases. It does not specify ordering or pagination, but that is acceptable for such a 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 compensates by specifying that session_id comes from convoopen and must be in format sess_v2_..., adding critical meaning beyond the schema's type definition.

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, with specific return fields (job IDs, statuses, types, timestamps). This differentiates it from sibling inspect tools like awsinspect or convoinspect which focus on other 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?

The description provides explicit usage scenarios: see deployment history, find job IDs for logs, check successes/failures. It also states the requirement for session_id from convoopen. However, it does not mention when not to use this tool versus alternatives like tfstatus or 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?

Discloses it's a read operation (readOnlyHint true) and adds detail about two timestamps (updated_at and last_refresh_at) and their meaning, going 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?

Concise yet informative, with clear sections (MONITORING, then body, LIVENESS, TIP). 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?

Covers return values (job status, metadata, timestamps) adequately for a simple tool. Missing explicit error handling or response structure, but sufficient given low 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 coverage, description compensates by explaining session_id format and source, and job_id purpose and source. Could be more explicit about job_id format.

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

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

Clearly states it's for checking Terraform deployment status, distinguishes from tflogs (stream logs) and tfruns (discover IDs), and specifies it returns job status and metadata.

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 when to use (quick status check), when not to (for logs use tflogs), and provides prerequisites (session_id from convoopen, optional job_id from tfruns). Also includes a tip about timestamps.

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