InsideOut (Riley)

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

Annotations already declare readOnlyHint/openWorldHint, but the description adds real substance beyond them: it fetches temporary read-only credentials and hits the AWS API directly, describes the three response tiers and their token cost, and discloses that metrics discovery needs no credentials while billing actions need ce:GetCostAndUsage/ce:GetCostForecast IAM permissions.

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

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

Front-loaded with the prerequisite and purpose, and the header-based sections (RESPONSE TIERS, REQUIRES, METRICS, BILLING, EXAMPLES) make it scannable despite its length. Slightly redundant: the purpose is restated three times across the opening lines and the 'Use this tool when...' sentence.

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

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

For a 6-param, multi-service inspection tool with an output schema, this covers everything an agent needs: gating prerequisite, credential/session format (sess_v2_...?token=...), the full service enum rationale, metric and billing sub-flows, and worked examples. Return values need not be explained since an output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely enriches it with concrete filter JSON ('{"hours":6,"period":300}', '{"days":7,"granularity":"DAILY"}'), action discovery via action='list-actions', and the coupling of detail/raw to response tiers. Minor gap: it says detail/raw may be omitted while the schema lists them as required.

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

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

States a specific verb and resource ('Inspect AWS infrastructure / deployed AWS resources') and immediately narrows scope to resources created by a deployment attempt. An agent can distinguish it from convoinspect, gcpinspect, and the tf* family without opening a schema.

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 prerequisite ('requires a prior deployment ATTEMPT', check convostatus for hasDeployAttempt=true), explicit trigger ('when the user asks about the status or details of their deployed infrastructure'), and an explicit edge case ('works even after failed deploys to inspect orphaned resources'). It also names the sibling (convostatus) that gates this call.

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 cover only the safety profile (readOnly/openWorld/not idempotent), while the description adds substantial behavior: per-sub and total budgets, concurrency cap 8, 512 KB cap with truncated=true envelopes, that partial failure is expected, and that a credential fetch failure still leaves cred-less probes succeeding. This is exactly the extra context the structured fields cannot carry.

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

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

Front-loaded purpose, then prerequisite, then budgets, partial-failure guidance, requirements, and examples. Given the genuine complexity (32 sub-probes, budgets, concurrency, truncation), the length is justified and every section earns its place; labeled blocks make it scannable rather than rambling.

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?

An output schema exists and annotations carry safety, yet the description still supplies prerequisites, budget/truncation semantics, partial-failure handling, response entry shape, credential-fetch caveat, and examples. Nothing an agent needs to call a batch tool correctly is missing.

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

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

Schema coverage is 100% and documents subs/service/action/filters, so the baseline is 3; the description adds value with worked example calls showing the subs array shape and the JSON-encoded filters pattern. It stops short of explaining per-sub timeout interaction but goes beyond the schema with concrete 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?

States a specific verb and resource ('BATCH INSPECTION: run up to 32 AWS inspect probes in one call') and immediately distinguishes itself from the singular sibling: batch for >3 resources, awsinspect for discovery (list-actions) or full metadata/raw output on one resource. An agent can route correctly without opening either schema.

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 when-to-use ('when you need to check more than ~3 resources'), stated prerequisite (deploy attempt / hasDeployAttempt=true), and clear exclusions with the alternative named ('batch is not the place for discovery'; use singular awsinspect for full metadata/raw). Nothing is left to inference.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true, idempotentHint=false), so the bar is lower. The description adds real behavioral context: this is a blocking wait operation, it requires the session_id credential from convoopen, and it enforces a max timeout of 55s (default 50, Cursor-specific). It doesn't discuss failure modes if the wait times out again, but overall it meaningfully supplements 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?

Front-loaded with the core purpose, then clearly sectioned into USE WHEN / REQUIRES / OPTIONAL. Headers and emoji are slightly decorative but every line carries actionable information with no redundant 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?

Covers the trigger condition, credential source, and timeout constraints for a blocking tool. An output schema exists, so the brief 'returns the same format as convoreply' note is sufficient and the description needn't detail return values further.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the token-suffix requirement on session_id. The description restates the required/optional split and the source of session_id (convoopen), adding only marginal value beyond what the schema provides, which matches the baseline 3.

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

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

States a specific verb+resource: waiting for a pending response from Riley after a convoreply timeout. It explicitly distinguishes itself from the sibling convoreply by noting it continues waiting 'without resending the message', so an agent can tell them apart without opening either schema.

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 'USE THIS TOOL WHEN: convoreply returned a timeout error' gives the exact triggering condition and names the alternative tool (convoreply). When-to-use is unambiguous and no inference is required.

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 safety profile is covered; the description's 'Read-only; never mutates session state' merely restates it. The enumerated return payload (message history plus workflow step, cloud, deployment status, drift state) is largely duplicative of the existing output schema. It does not explain what idempotentHint=false means in practice or disclose any auth/credential nuance beyond what the schema already states.

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

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

Front-loads the core capability before the routing bullets, and the bulleted sibling list is compact and earns its place as a disambiguation aid. The trailing 'REQUIRES:' line duplicates the schema and is the one section that could be dropped.

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 an output schema present, the description needn't explain return values, and it covers the calling precondition, the read-only guarantee, and sibling routing, so an agent has everything needed to invoke it. The only shortfall is redundancy rather than a genuine gap — it over-explains returns that the output schema already supplies.

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

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

Only one parameter, and schema description coverage is 100% — the schema already documents the sess_v2_*?token=* pattern and warns not to strip the token suffix. The description's 'REQUIRES: session_id (format: sess_v2_...)' restates the schema rather than adding new semantic detail, so the baseline 3 applies.

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

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

States a specific verb (View/Inspect) and resource (a session's conversation transcript and metadata), and explicitly positions itself as the 'transcript-reader companion to the other read tools' while naming convostatus, tfruns, and stackversions as distinct siblings. An agent can distinguish it from the thirteen other read/inspect tools without opening a schema.

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

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

Gives an explicit trigger ('what did I say earlier?', retracing why a session ended up where it did) and routes each alternative use case to a specific sibling with the condition that selects it (convostatus for live stack/config/pricing, tfruns for deployment history, stackversions for version ladders). Nothing is left to inference.

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

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

Goes well beyond the annotations: it discloses that the response carries an intro message from 'Riley' to relay verbatim, that questions must be forwarded rather than answered, and that a session_id with a ?token= credential suffix appears in metadata and must be passed unmodified to downstream tools or they 401. This is exactly the operational context annotations (readOnly=false, openWorld=true) cannot convey.

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

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

Front-loads the workflow position, which is good, but the body is heavy with emoji warnings and repeats the session_id/?token= instruction across two consecutive paragraphs. Every point is useful, yet the same message is stated more than once, costing structure.

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 session-opening tool with an output schema, the description supplies everything an agent needs: the trigger, the return handling (relay message, forward questions), the credential-passing contract for all downstream tools, and full parameter guidance. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it tells the agent to confirm project_context with the user before sending and enumerates what to include and explicitly exclude (secrets, PII, source code), and explains source auto-detection and its effect on the connect button.

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

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

States a specific verb and resource: 'Open an InsideOut V2 session and receive the assistant's intro message.' It is placed within a numbered workflow (Step 1 of 4) and clearly distinguished from siblings like convoreply, convostatus, and tfgenerate, which are named as downstream steps.

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

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

Gives explicit trigger conditions ('setup my cloud infra', 'provision infrastructure', 'start insideout') and positions itself as the entry point of a 4-step workflow, so the agent knows both when to call it and how it relates to alternatives.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, but the description goes well beyond them: it discloses that the call blocks for a response (timeout default 50, max 55), that the response is gated on server-side signals, and it carries a strong behavioral constraint ('DO NOT answer Riley's questions yourself... STOP and wait'). This is real operational context the annotations cannot convey.

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

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

The workflow step is front-loaded and the sections are labeled, but the description is bloated: the 'do not answer Riley' warning is repeated three times in escalating caps, and the response-signal list restates gating rules already covered in the workflow section. Emoji-heavy ALL-CAPS formatting adds length without adding 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?

With an output schema present, return values need not be explained, yet the description usefully summarizes the key in-band signals ([TERRAFORM_READY], [[BUTTON_TF_*]]). Given this is a stateful, non-idempotent, open-world call, the description supplies the session requirements, blocking behavior, and downstream gating an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value: it flags session_id's provenance and exact-pass-back requirement, gives environment-specific timeout advice ('For Cursor, use 50'), and constrains project_context to genuinely new details with an explicit example. It stops short of 5 only because much of this overlaps the schema's own 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 a specific verb and resource: 'Send a user message to the active InsideOut session and receive the assistant reply,' and adds the return semantics ('contains a clean message from Riley'). Combined with the 'Step 2 of 4' framing, an agent can distinguish this from convoopen, convostatus, and convoawait without opening any schema.

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 routing is provided: the conversation → tfgenerate → tfdeploy phase order, the condition that unlocks tfgenerate ('when terraform_ready=true appears in THIS tool's response'), and per-signal instructions for tfplan, tfdeploy, and tfdestroy. It even names convostatus as the progress-checking alternative. Nothing about when to call this vs. siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the session credential requirement ('session_id from convoopen response', never strip the ?token= suffix) and the meaning of each phase indicator. It does not disclose whether the tool is a pure snapshot or can mutate design state.

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

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

The purpose is front-loaded and the usage triggers are easy to find, which is good. However, the bulk of the text is a multi-level enumeration of return values — an output schema already exists, so this section is largely redundant and crowds out more decision-relevant content.

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

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

Given an existing output schema, the description carries the parts that matter: what the tool answers, when to call it, and the credential constraint on session_id. It is complete enough for correct invocation; the only soft spot is the absence of any disambiguation against the many sibling inspection 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 description coverage is 100%, so the baseline is 3, and the description does not exceed it meaningfully — the format and token-preservation guidance it repeats is already spelled out in the schema. It does add one piece of information the schema lacks: that session_id originates from a convoopen response. The optional job_id and its 'latest job' fallback behavior are never mentioned.

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

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

The description states a specific verb and resource — 'View the current infrastructure stack for a session' — and itemizes what that stack view contains (components, config, pricing, phase indicators). It is clear on its own, but it never distinguishes itself from near-neighbors like convoinspect, awsinspect, or gcpinspect, leaving the agent to guess which inspection tool applies.

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 trigger phrases ('what is my current stack?', 'show my infrastructure', 'what have I selected?') that map directly to invocation conditions. It stops short of naming when NOT to use it or which sibling handles the adjacent cases, so no exclusions or alternatives are stated.

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

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

Annotations only cover the safety profile (non-destructive, idempotent, open-world); the description adds the blocking/polling behavior, the timeout bound, the prerequisite that a URL must be surfaced first, and how credentials are used. That is substantial context beyond what structured fields provide.

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 front-loaded with headers and a numbered workflow that an agent can act on. Slightly over-written: the 'IMPORTANT: do not call without showing URL' maxim restates workflow step 1, and the InsideOut security paragraph is persuasive filler rather than operational guidance.

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 an output schema exists, return values needn't be explained; prerequisites, session source, trigger errors, timeout semantics, and the post-success next step (call tfdeploy) are all present. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the description largely restates it (session_id from convoopen, cloud aws/gcp, timeout default 300 max 600). The one added nuance, that the ?token= suffix is part of the session credential and must not be stripped, is also already in the schema, so this is baseline rather than enrichment.

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

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

States a specific verb and resource: wait/poll for the user's cloud credentials to appear on the session. The Luther Systems subscription step and the polling mechanism make it clearly distinct from siblings like convoawait or tfstatus.

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 trigger condition ('tfdeploy returns auth_required, no_credentials, or credentials_expired'), explicit ordering rule ('Do NOT call without first showing the connect URL'), and a numbered workflow that names tfdeploy as the follow-up. Both when-to-use and when-not-to-use are covered.

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, yet the description adds real context beyond them: it fetches temporary read-only credentials and queries the GCP API directly, it works after failed deploys to surface orphaned resources, and it names the token cost of each response tier (~500 tokens for summary). It also enumerates the IAM roles required for metrics, secret health, and billing.

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

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

Front-loaded and well sectioned (PREREQUISITE, RESPONSE TIERS, REQUIRES, METRICS, BILLING, EXAMPLES), so an agent can skim to the tier defaults. It loses a point for redundancy: the 27-service list repeats the schema enum verbatim, and 'Inspect deployed GCP resources after a deployment attempt' restates the header and the following usage sentence.

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

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

An output schema exists, so return values need no explanation, and everything else an agent needs is present: credential prerequisites, IAM roles, tier selection with defaults, service/action discovery, and worked examples. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema descriptions: how detail/raw interact with resource filters to select a tier, a concrete filters JSON with a 'period' key the schema omits, the session_id format and the deploy-attempt requirement tied to it, and per-service metric label breakdowns. It stops short of documenting every service/action combination.

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

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

States a specific verb and resource ('Inspect GCP infrastructure for a deployed project') and scopes it to resources created by a prior deployment attempt. The GCP focus plus the deploy-attempt precondition cleanly separates it from awsinspect and from gcpinspect_batch without opening either schema.

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

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

Gives an explicit trigger ('Use this tool when the user asks about the status or details of their deployed GCP infrastructure'), an explicit precondition ('requires a prior deployment ATTEMPT... Check convostatus for hasDeployAttempt=true'), and routes between sub-actions (action="list-actions" for discovery, list-metrics vs get-metrics, service=billing for billing). When, when-not, and alternatives are all present.

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

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

The description provides rich, non-obvious behavioral constraints, such as the prerequisite of a deploy attempt (`hasDeployAttempt=true`), the specific performance characteristics (fan out, single credential fetch), and the critical instruction that partial failure is expected and agents should not abort.

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

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

Despite its length, the structure is highly effective. It front-loads prerequisites and core limitations (32 probes), then moves logically through performance, constraints, failure policies, and finally provides usage examples, making zero sentences feel wasted.

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

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

Given the complexity of batch operations, failure handling, and performance characteristics, the definition is exceptionally complete. It details everything from concurrency caps to the specific truncation policy for large responses.

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

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

Although schema coverage is 100%, the description adds vital semantic meaning. It specifies that the session_id must include the full `?token=...` suffix, and it provides practical examples of filter usage and clarifies the difference between action types (e.g., discovery vs. time-series metrics).

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 title and description clearly state the purpose: running up to 32 GCP inspect probes in a single batch call. It explicitly distinguishes itself from the singular tool, gcpinspect, by stating the batch is not suitable 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 guidelines are exhaustive. It tells the agent exactly when to use the tool (when checking >~3 resources), and crucially, when *not* to use it, directing agents to gcpinspect for discovery or detailed raw output.

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 safety profile is covered. The description adds real behavioral context beyond that: responses carry hints with next_actions and related_tools, telling the agent to expect follow-up suggestions.

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 short, front-loaded sentences: purpose first, then invocation modes, section list, and response shape. Every sentence carries information, though the section enumeration overlaps with the schema.

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

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

An output schema exists, so return values need no prose, and the description still notes the hint structure. For a single optional-enum guidance tool this is sufficient; only a note on when to reach for help is absent.

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

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

Schema coverage is 100% and the single enum parameter is fully documented in the schema, including the omitted-behavior default. The description merely restates the section names, adding no syntax or meaning beyond the structured field. Baseline 3 applies.

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

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

States a specific verb and resource ('Get workflow guidance') and scopes it to the InsideOut infrastructure toolset. This clearly separates it from every sibling, all of which are operational tools (tfdeploy, awsinspect, etc.) rather than meta/guidance.

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

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

Gives concrete invocation guidance: help() for a compact overview vs help(section=...) for a detailed guide, and enumerates the four sections. There are no competing alternatives to exclude, but it also doesn't state when in an agent's workflow it should be called.

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 mark this as read-only and open-world, and the description adds substantial non-obvious behavior: the default comparison target, empty baseline after a destroy, staleness of pending drafts, and the fact that live IR via chat history is always current. These details materially affect how the agent interprets the diff.

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

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

Front-loads the core output description, then groups default behavior, explicit-version usage, and session prerequisite in short paragraphs. Every sentence contributes, though the chat-history justification and format repetition add some length beyond the minimum.

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

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

Given the tool's complexity and the presence of an output schema plus read-only annotations, the description provides all missing context: prerequisite session credential, default behavior, explicit-version semantics, and edge cases like empty baselines. Nothing needed to call it correctly is absent.

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

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

Schema coverage is 100% and already documents session_id format and version parameters, but the description adds meaning by correcting the default target (live design, not pending draft) and by stating that explicit integers compare any two saved versions. Some session_id format detail is repeated from the schema, keeping this from a 5.

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?

Names a specific verb (compare/diff) and resource (stack versions), states the output is a structured diff of what tfdeploy would deploy now, and implicitly separates it from sibling stackversions/tfplan by focusing on version-to-version comparison. An agent can identify the operation without opening the schema.

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

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

Explains when to rely on default behavior (no version arguments compare the last successfully deployed version against the current live design) and when to pass explicit from_version/to_version integers to compare saved versions. It adds important caveats about pending drafts and empty baselines, but does not explicitly name sibling alternatives such as using stackversions to list versions first.

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 cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower, but the description adds valuable behavior beyond them: the single-draft rule (updates an existing draft in-place) and that it copies components/config/pricing. This meaningfully explains what the mutation does without contradicting any hint.

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

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

The definition is front-loaded with the core action, then behavior (single-draft rule), then prerequisites. It is appropriately sized and mostly waste-free, though the REQUIRES line partly duplicates the schema's required fields and format notes.

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?

An output schema exists so return values need not be described, and the description covers behavior, the single-draft edge case, and prerequisites. It stops short of stating permission/authorization needs or what happens to non-copied fields, leaving minor gaps for a first-time caller.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (version's 'use stackversions to list', session_id's exact format). The description largely restates those requirements, adding little syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and outcome: 'Create a draft version by reverting to a previous version's config,' and elaborates what gets copied (components, config, pricing). It is clearly a rollback/draft-creation tool rather than a listing or diff tool. However, it does not explicitly contrast itself with siblings like stackdiff or stackversions beyond naming stackversions as a prerequisite.

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 prerequisite guidance is given: 'Use stackversions first to find available version numbers,' and the REQUIRES line names the two required inputs. There are no negative exclusions (when not to use it) or named alternative tools for other scenarios, which would be needed for 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 readOnlyHint=true and openWorldHint=true, so the safety profile is partly covered. The description adds real value beyond them: newest-first sort order, the status vocabulary (draft/confirmed/applied), and the auth prerequisite that session_id must come from convoopen. It stops short of noting volume/pagination or rate limits.

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, front-loaded blocks: what it returns, when to use it, and the prerequisite. Little waste, though the REQUIRES line partially repeats the session_id format already covered in the schema.

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

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

One required parameter fully documented, output schema present so return values need no further explanation, and the description covers ordering, returned fields, use cases, and the auth prerequisite. An agent has everything needed to call it correctly.

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

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

With one parameter and 100% schema description coverage, the schema already carries the format details and the ?token= suffix warning. The description echoes the requirement and usefully traces the value's origin back to convoopen, but adds no syntax the schema lacks, so the baseline 3 applies.

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

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

States a specific verb and resource ('List all stack versions for a session') and adds ordering (newest first) plus the fields returned (version number, status, change summaries, timestamps). It is unambiguous what the tool does, but it never names or contrasts a sibling such as stackdiff or stackrollback, which is what a 5 would require.

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

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

Gives three concrete use cases: see design history, review what changed between iterations, and find a version number to roll back to. This gives clear context for when to reach for it, and 'find a version number to roll back to' implicitly routes toward stackrollback, but there is no explicit when-not or named alternative.

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

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

Annotations already declare this is a non-read-only, non-destructive, open-world write, so the safety profile is covered. The description adds real value beyond that: the destination team, the initiator tracking semantics ('user' vs 'agent'), and the accepted categories/examples of what constitutes reportable feedback.

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?

It is longer than most, but well front-loaded with FEEDBACK/REQUIRES/OPTIONAL headers and each section (categories, initiator semantics, examples) earns its place. Slight redundancy between the prose intro and the examples.

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 an output schema present, return values need not be explained. Required/optional parameters, category enum, and initiator semantics are all covered. The only shortfall is the 'security' category mentioned in prose but absent from the schema enum, leaving minor ambiguity.

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

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

Schema coverage is 100%, so the schema already documents each parameter; the description goes further by restating required vs optional fields with intent (user_email 'for follow-up', source 'default: mcp', initiator meaning). One caveat: it lists 'security' as a category, but the schema enum omits it, creating a small mismatch.

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

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

The description opens with a specific verb+resource ("Submit feedback, bug reports, or feature requests to Luther Systems") and names the destination team. It is trivially distinguishable from all siblings, which are terraform/AWS/conversation tools with no overlapping function.

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

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

It clearly states when to use it (forward user feedback; agent self-reporting issues) and provides three concrete trigger examples. It lacks explicit when-NOT-to-use guidance or named alternatives, but no sibling competes for this function, so the gap is minor.

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 flag destructive=true and openWorld=true, but the description adds a lot beyond them: the 15+ minute long-running nature, the session-level single-flight guard and the tf_job_conflict response contract, the default-fail-on-drift behavior, and the full credential flow. This is unusually rich operational context for a mutation tool.

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

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

Front-loaded with WORKFLOW step and the core action, and the labeled sections (REQUIRES, OPTIONAL, CREDENTIAL FLOW) make it scannable. Slightly over-long: force_new and ignore_drift are explained both in prose and again in the schema, and the return-value sentence is redundant given the output schema.

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

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

For a destructive, long-running, open-world deploy tool with 7 params, it covers prerequisites (session_id format), optional overrides, conflict handling, drift policy, and credential recovery. With an output schema present, it correctly does not over-explain return values.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: the preview-then-apply sequence for plan_id (tfplan → tflogs → tfdeploy), the single-flight interaction of force_new, and the drift-override semantics of ignore_drift. Note a minor inconsistency: the description says sandbox defaults to false while the schema says true is the MCP default, which is worth resolving.

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

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

States a specific verb and resource ('Deploy infrastructure by starting a Terraform job') and frames it as Step 4 of 4, which immediately distinguishes it from tfplan, tfdestroy, tfdrift, and tfstatus. An agent can place this tool in the workflow without opening any schema.

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

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

Explicitly states when to use it (after Terraform files are generated), names alternatives for adjacent needs (tfstatus to monitor, tflogs/tfdrift before overriding drift, credawait for missing credentials), and gives a clear when-not rule for force_new ('only when the existing run is provably wedged'). Nothing is left to inference.

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

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

Goes well beyond the destructiveHint annotation by disclosing that this starts a long-running job, that only one TF job per session may be in flight, that a conflict returns tf_job_conflict with a live job_id, and that the session is retained afterward with hasDeployment set to false. These are exactly the operational traits an agent needs that structured annotations cannot convey.

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

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

The lead line is front-loaded with the verb, and labeled blocks (IMPORTANT, SINGLE-FLIGHT, REQUIRES, OPTIONAL, PREREQUISITE) make each fact scannable. It is dense but every sentence carries operational weight; nothing is redundant filler.

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

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

With an output schema present, return-format detail is unnecessary, and the description instead supplies the missing context: prerequisites, job lifecycle, conflict recovery path, and post-destroy session state. An agent has everything needed to invoke it correctly and handle the single-flight 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 coverage is 100%, so the baseline is 3, but the description adds genuine guidance beyond the schema: it explains that force_new should only be used when a run is 'provably wedged' and clarifies the session_id provenance (convoopen) and the credential suffix. That extra context lifts it above baseline without fully replacing schema detail.

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

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

States a specific verb (destroy/tear down) and resource (previously deployed infrastructure) with exact mechanism ('Oracle destroy endpoint'). Clearly distinguishes itself from its sibling tfdeploy, and the scope ('previously deployed infrastructure') leaves no ambiguity about what is being acted on.

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 names alternatives for monitoring (tfstatus/tflogs) and gives a precise condition for the force_new override ('only when the existing run is provably wedged'). It also states the precondition (prior successful deployment) and the conflict-handling flow, so an agent knows when and how to call it versus reach for tfstatus.

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 asserts twice that this is a read-only operation ('read-only drift detection check', 'it does NOT modify any infrastructure'), yet the annotations declare readOnlyHint=false. An agent receiving these two signals would be genuinely unsure whether invoking this tool can mutate state, which is exactly the kind of conflict the rubric penalizes. Annotation 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?

Well-structured with labeled sections (DRIFT CHECK, SINGLE-FLIGHT, REQUIRES, PREREQUISITE, OPTIONAL) and the core purpose is front-loaded. It runs long, but nearly every line carries operational information an agent needs (conflict handling, credential format, prerequisite).

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?

An output schema exists so the return value needn't be explained, yet the description still tells the agent it returns job_id and to stream results with tflogs. Combined with the single-flight guard, session format, project_id prerequisite, and override escape hatch, nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains force_new as bypassing the single-flight guard and constrains its use ('use only when the existing run is provably wedged'), and it reinforces the session_id format/credential requirement beyond the schema text.

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

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

States a specific verb+resource ('Run a read-only drift detection check') and scopes it precisely ('checks whether deployed infrastructure has drifted from the expected Terraform state'). It is clearly distinguishable from sibling tools like tfdeploy, tflogs, and tfstatus, which it names directly.

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 routes the agent: 'Use tflogs to stream the drift check results', and on conflict 'attach with tfstatus/tflogs, or pass force_new=true'. It also gives a when-not for force_new ('Use only when the existing run is provably wedged') and names tfdeploy(ignore_drift=true) as the downstream alternative when drift is found.

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=false, destructiveHint=false, idempotentHint=true, and the description does not contradict them. It adds meaningful behavior beyond the annotations: default response returns a summary table + download URL rather than inline code, include_code triggers a fallback path, and there's a required user-confirmation step before download. It does not say whether generation overwrites existing files in ./insideout-infra/, a minor gap.

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

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

Front-loaded with the workflow step and purpose, and organized under clear headers, but there is noticeable redundancy: the terraform_ready prerequisite is asserted three separate times and the fallback/retry behavior is stated twice. It is longer than necessary without being disorganized.

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

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

Even though an output schema exists (so return values need not be described), the description goes further and explains the shape of the response (summary table + URL vs inline code). Prerequisite state, fallback behavior, required user confirmation, and the handoff to tfdeploy are all covered.

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

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

Schema description coverage is 100%, so both parameters are already documented; the schema itself explains the ?token= suffix and the include_code fallback. The description restates these rather than adding new semantics, though noting session_id originates from convoopen adds slight provenance value. Baseline 3 is appropriate.

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

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

Specific verb+resource ('Generate Terraform files') scoped to an InsideOut session that has completed infrastructure design. Clearly distinguishable from siblings like tfplan, tfdeploy, and tfdestroy, which operate at other stages. The 'Step 3 of 4' framing further anchors it in the 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?

Explicit when-to-use ('convoreply has returned with terraform_ready=true, OR the user asks to see the terraforms') and explicit when-not ('DO NOT call this while convoreply is still running or before terraform_ready is confirmed'). It also routes the user forward to tfdeploy after generation, naming the alternative.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing the dual REST/SSE execution path, the 50s default/55s max timeout ceiling, and the context-window warning about hundreds of log lines. The pagination cursor lifecycle (last_event_id returning only new logs) is a genuinely non-obvious behavioral trait.

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?

Bold headers and a numbered pagination flow make it scannable and front-loaded with purpose before mechanics. The RESPONSE FIELDS block partially duplicates the existing output schema, which is the only wasted space.

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

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

With an output schema present, the description needn't re-explain return values, yet it still supplies the operational context an agent needs: prerequisites (session_id from convoopen), pagination termination condition, and the context-blowup risk. Nothing material is missing for correct invocation.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns above that by adding selection guidance the schema lacks — tail:50 for completed jobs, timeout defaults, job_id discovery via tfruns — though it doesn't add much on the session_id token format beyond what the schema states.

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

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

States a specific verb and resource ('Fetch Terraform deployment logs') and immediately distinguishes the two operating modes (completed jobs via REST vs running jobs via SSE). An agent can tell exactly what this tool returns and how it differs from tfstatus or tfruns.

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

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

Gives concrete routing advice: use tfruns to discover job_id, use tail for completed jobs, and a three-step pagination recipe until complete:true. It lacks explicit when-not-to-use guidance against near siblings like tfstatus or tfoutputs, which keeps it from 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?

Adds real context beyond the annotations: sensitive outputs are redacted as '(sensitive)', outputs are only available after a successful deploy, and lifecycle filters restrict which step's outputs are returned. With readOnlyHint/openWorldHint already covering the safety profile, this is solid supplementary disclosure, though nothing is said about staleness or size of the returned set.

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

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

Front-loaded with the core purpose and the redaction/default behavior, but the trailing REQUIRES/OPTIONAL block duplicates the input schema near-verbatim, and the 'INSPECTION:' prefix adds no information. Serviceable but with redundant bulk.

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?

An output schema exists so return values need not be explained, and the description covers the essentials an agent needs: prerequisite session_id, default selection behavior, filtering options, and redaction of sensitive values. Only minor gaps (failure behavior when no successful deploy exists) remain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates the schema (job_id as specific deployment, lifecycle as a step filter) and adds only the 'cloud-provision' example already present in the schema, so it contributes little new meaning despite being accurate.

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?

Specific verb+resource ('Retrieve Terraform outputs from a completed deployment') with a clear scope statement about default (latest successful deploy) versus explicit job_id. It implies but never explicitly contrasts itself with siblings like tflogs/tfstatus, which also read deployment state, so differentiation is only partial.

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?

Clear context for use: outputs come from a *completed* deployment, default selects the latest successful apply, and job_id/lifecycle narrow the scope. It also names convoopen as the source of the required session_id, giving a prerequisite chain, but it names no explicit alternative tool or exclusion.

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

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

Goes well beyond the annotations by disclosing the single-flight guard, the tf_job_conflict response and its handling, returned identifiers, and credential prerequisites. The one gap is that it never reconciles its 'without applying any changes' framing with readOnlyHint=false — an agent is not told that a job/plan artifact is still created or whether state is refreshed.

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 front-loaded with labeled sections (PREVIEW, SINGLE-FLIGHT, REQUIRES, OPTIONAL, CREDENTIAL HANDLING) that make it scannable. Slight redundancy between the header line and the second sentence ('preview' vs 'without applying any changes') costs it a point.

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 an output schema covers return values and annotations cover the safety profile, the description supplies everything else needed to invoke correctly: prerequisite session format, conflict behavior, override condition, credential requirement, and the follow-up deploy step.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value: it frames session_id as coming from convoopen, states the exact sess_v2_... format, and constrains force_new ('Use only when the existing run is provably wedged'), which the schema does not.

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

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

States a specific verb and resource ('Run terraform plan to preview infrastructure changes') and immediately scopes it as non-applying. It is clearly distinguishable from siblings tfdeploy, tflogs, tfstatus, and tfdestroy, which the description names directly.

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 when-to-use plus alternatives: 'Use tflogs to stream the plan output', 'After the plan completes, use tfdeploy with plan_id to apply', and the force_new escape hatch versus attaching with tfstatus/tflogs on tf_job_conflict. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavior beyond that: the returned field set and the credential requirement ('REQUIRES: session_id from convoopen response'). One minor discrepancy: it says types are 'apply/destroy' while the schema lists apply/destroy/plan/drift.

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

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

Front-loaded with an INSPECTION label, then purpose, return fields, usage, and prerequisites in clearly separated blocks. Slightly longer than necessary given an output schema exists, but every sentence is relevant and scannable.

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

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

With an output schema present, explaining return values is optional, yet the description still covers purpose, usage, and the required credential format, leaving no gap for an agent to call it correctly. The only shortfall is the minor type-list mismatch with the 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?

Schema description coverage is 100%, so the parameter's format and token-suffix warning are already fully documented in the schema. The description only restates the source tool (convoopen) and a truncated format hint, adding little beyond what the schema provides — the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('List all Terraform deployment runs for a session') and names the exact fields returned (job IDs, statuses, types, timestamps). It is clearly distinguishable from log- or status-oriented siblings, though it never names a sibling explicitly.

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

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

Gives three concrete use cases — viewing deployment history, finding job IDs for log inspection, and checking success/failure — which routes the agent well. It does not, however, state when to prefer another tool (e.g. tflogs or tfstatus) or any exclusion.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing the liveness model: updated_at only bumps on semantic change while last_refresh_at stamps every successful Oracle poll, which is exactly what an agent needs to distinguish a stalled job from a stale row. It also states that no logs are streamed and what identifiers the response carries.

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 lead line and the tflogs hand-off are front-loaded and earn their place, and the liveness bullets carry real information. The trailing 'workflow.usage prompt' tip is vague filler, and the REQUIRES/OPTIONAL block duplicates the schema.

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

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

An output schema exists, so return values need not be spelled out, yet the description covers auth, sibling alternatives, and the timestamp semantics that matter for polling. The only loose end is the ambiguous pointer to the workflow.usage prompt, which gives no concrete action.

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

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

Schema description coverage is 100% and the schema already documents both parameters, including the sess_v2_*?token=* format warning. The description mostly restates those REQUIRES/OPTIONAL lines; the only genuinely new fact is that job IDs can be discovered via tfruns.

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

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

States a specific verb and resource — 'check the current status of a Terraform deployment job' — and immediately narrows the scope ('without streaming logs'). It is distinguishable from tflogs and tfruns, which are named in the text.

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 routing: use tflogs to stream the actual deployment logs, use tfruns to discover job IDs. It also states the precondition (session_id from convoopen) and when job_id is optional, so an agent knows exactly when this tool is and is not the right call.

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