InsideOut (Riley)

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

Beyond annotations (readOnlyHint, openWorldHint), the description explains it fetches temporary read-only credentials, queries AWS API directly, and details response tiers (summary, detail, raw). No contradictions.

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

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

The description is well-structured with sections (PREREQUISITE, RESPONSE TIERS, etc.) and examples. It is comprehensive but slightly verbose; could be tighter.

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

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

Complete for a complex tool: covers prerequisites, response types, supported services, metrics/billing, and examples. No output schema, but description explains return formats.

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

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

Schema coverage is 100%, but the description adds value by explaining session_id format, service list, action types, filters usage, and response tiers with 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?

The description clearly states it inspects AWS infrastructure for a deployed project, using the verb 'inspect' and specifying the resource. It distinguishes from sibling tools like awsinspect_batch and gcpinspect.

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 prerequisites (prior deployment attempt, checking convostatus), when to use (user asks about infrastructure status), and provides alternatives (awsinspect_batch for batch operations).

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. The description adds extensive behavioral context: partial failure expected, credential fetch behavior, response structure with truncation, budgets (max 32, timeouts, concurrency cap, 512KB cap). It explains that batch responses are always summarized and singular tool for detail/raw. 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?

Well-structured with clear sections: purpose, prerequisite, when to use, budgets, partial failure, required fields, supported services, examples. Front-loaded with key info. Each 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?

Despite no output schema, the description explains the response structure (ordered array with index, service, action, ok, result, error), error handling (partial failure), truncation behavior, and limitations (summarized only). Lists all supported services. Covers all necessary context for correct usage.

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

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

Schema covers 100% of parameters, but the description adds significant meaning: explains that sub-probes run in parallel with concurrency 8, 30s per-sub timeout, 60s total, partial failure expected. Provides examples and explains the credential fetch optimization. The description enriches the schema's definitions.

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

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

The description clearly states it performs batch inspection of AWS resources, running up to 32 probes in one call. It distinguishes from the singular awsinspect tool by explicitly noting when to use each: use this for >3 resources, use singular for discovery or full metadata. The verb 'Batch-Inspect' and resource 'AWS Infrastructure' are specific.

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

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

Provides explicit when to use this tool vs alternatives: 'Use this when you need to check more than ~3 resources.' Also states when not to use (for discovery or full metadata, use singular awsinspect). Includes prerequisite (deploy attempt required, check convostatus). Gives examples of valid calls.

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

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

Annotations indicate readOnlyHint=true, and description adds behavioral details: polling behavior, timeout constraints, return format (same as convoreply). 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 emoji, sections, bullet points. Every sentence is meaningful and concise. 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?

Tool has 3 parameters, all described. Context of why it exists (timeout recovery) is clear. No output schema, but return format is referenced via convoreply. Complete for its complexity.

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

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

Schema coverage is 100%, providing baseline 3. Description adds extra value: explains session_id source, message_id from timeout error, timeout defaults and Cursor-specific guidance, and format requirements.

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

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

The description clearly states the tool waits for a pending response after a convoreply timeout, with specific verb and resource. It explicitly distinguishes from convoreply by stating it is used when convoreply returned a timeout error.

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 convoreply timeout error), what it does (continue waiting without resending), and provides requirements and optional parameters. 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?

The description discloses behavioral traits beyond annotations: it states 'Read-only; never mutates session state,' which aligns with readOnlyHint=true. It also warns about the session_id format and the importance of preserving the token suffix as part of session credentials.

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 and well-structured, with clear sections (INSPECTION, returns, companion tools, usage guidance, requirements). Every sentence adds value without redundancy. It is front-loaded with the primary action.

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

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

Despite having no output schema, the description provides complete context: it details exactly what is returned (message history + metadata), when to use the tool, the parameter requirement, and its role among sibling tools. No gaps are 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?

With 100% schema coverage, the description adds significant meaning to the parameter session_id: it explains the origin (from convoopen), the exact format (sess_v2_*?token=*), and a critical behavioral note to never strip the token suffix. This goes well beyond the schema's pattern and description.

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: 'View a session's conversation transcript and metadata.' It specifies the return value includes full message history and session meta. It differentiates from siblings by naming companion tools (convostatus, tfruns, stackversions) and positioning itself as the 'transcript-reader companion.'

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 usage guidance is provided: 'Use it when a user asks what did I say earlier? or you need to retrace why the session ended up where it did.' It also indicates when not to use it (read-only, never mutates state) and suggests combining with other tools for broader context.

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

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

Discloses critical behavior: returns a session_id with '?token=...' suffix, warns that omitting it causes 401 errors, and states that Riley asks questions that must be forwarded. These details go beyond the annotations (openWorldHint, destructiveHint) and add actionable 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?

Well-structured with sections, bold warnings, and a tip; front-loads critical workflow info. However, some repetition about the token suffix could be condensed. Still efficiently communicates necessary details.

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 and 3 parameters, the description fully covers purpose, usage, parameters, and behavioral constraints, tying into the larger workflow and sibling tools. Meets all needs for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, and the description enriches each parameter: source has auto-detection instructions, project_context includes security prohibitions and examples, github_username explains pre-filling. This adds significant context beyond the schema descriptions.

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

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

The description clearly identifies the verb 'Open' and resource 'InsideOut V2 session', and positions it as 'Step 1 of 4' in a workflow, distinguishing it from sibling tools like convoreply and tfgenerate. It states the action and expected output (assistant's intro message).

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

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

Explicitly lists triggering user intents (e.g., 'setup my cloud infra'), instructs the agent to forward questions to the user, and mentions the need to examine workflow.usage prompt. It also clarifies when not to answer on behalf of the user, providing clear usage boundaries.

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

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

Annotations indicate openWorldHint and destructiveHint, but the description adds significant behavioral context: workflow steps, critical warnings about not fabricating answers, key signals in the response, and parameter behaviors. 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 sections (WORKFLOW, CRITICAL, KEY SIGNALS). Every section serves a purpose, though the word count could be slightly reduced without losing clarity. Front-loading key signals earlier would 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 no output schema and 5 parameters, the description is very complete: covers workflow context, response signals, parameter details, and references sibling tools like convostatus. It leaves no ambiguity for an agent to misuse the tool.

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

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

The input schema has 100% coverage with descriptions, but the description adds nuance: explaining the session_id token suffix, timeout defaults, project_context constraints, and the text forwarding rule. This adds value beyond the schema.

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

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

The description clearly states the tool's role as Step 2 of 4 in the workflow, sending a user message to an InsideOut session and receiving the reply. It distinguishes itself from siblings like convoopen (starts session) and convostatus (checks progress) by specifying its position and function.

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

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

The description explicitly provides when to use (after convoopen, before tfgenerate), when not to (do not answer Riley's questions), and workflow phases. It also mentions alternatives like convostatus for checking progress and gives critical warnings about forwarding user questions.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds valuable context about the return content (components, config, pricing, phase indicators) without contradicting the annotations. It is transparent about what the tool inspects.

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 bullet points and a clear purpose statement at the top. It is slightly verbose but all sentences add value. No redundancy, and it is organized for quick scanning.

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 adequately explains the return value (components, config, pricing, phase indicators). It covers the key aspects of the tool's output and usage context, making it complete for an inspection 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 100%, so baseline is 3. The description does not add significant semantics beyond the schema descriptions for the two parameters. The mention of 'REQUIRES: session_id from convoopen' slightly reinforces but does not add new 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 views the current infrastructure stack for a session. It starts with 'INSPECTION: View the current infrastructure stack for a session' and elaborates with bullet points on what is returned. This distinguishes it from sibling tools like convoinspect which likely inspect other aspects.

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

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

Explicit usage guidance is provided: 'Use this tool when the user asks...' with example queries. It also states the prerequisite requirement for session_id from convoopen response. This is comprehensive and helps the agent decide when to invoke this tool.

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 adds that the tool polls until credentials appear, requires session_id, and is non-destructive. Annotations already indicate idempotentHint=true and destructiveHint=false, so the description aligns and adds context about secure credential handling and the URL flow. Could mention blocking behavior but overall good.

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 slightly long but well-structured with emoji, sections, and bullet points. It front-loads the purpose and usage. Some repetition of workflow could be trimmed, but remains clear and organized.

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

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

For a polling tool with no output schema, the description fully covers prerequisites (session_id), workflow (present URL, call tool, wait, then call tfdeploy), important notes, and required parameters. No gaps.

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

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

Schema coverage is 100%, but description adds valuable context: session_id format and warning not to strip suffix, cloud enum defaults, timeout defaults and max. These go beyond the schema's basic descriptions and ensure 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?

Explicitly states the tool waits for user to connect cloud account and subscribe, with a clear verb ('Wait') and resource ('Cloud Credentials'). It distinguishes from siblings like convoawait and awsinspect by specifying it is used after auth_required errors from tfdeploy.

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

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

Provides explicit when-to-use (when tfdeploy returns 'auth_required', 'no_credentials', or 'credentials_expired') and workflow steps, including the important instruction not to call before showing the connect URL. Alternatives are implied by the context of sibling tools.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true. Description adds significant behavioral context: uses temporary read-only credentials, queries GCP API directly, details response tiers, session_id format, IAM roles required, and specific behaviors for metrics and billing. 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?

Front-loaded with prerequisite warning and response tiers. Structured with clear sections, emojis for readability. Every sentence adds unique value—examples, IAM roles, edge cases (bastion alias, no time-series for Secret Manager). Efficient despite length.

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

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

Covers all necessary context: prerequisites, response formats, supported services, action patterns, metrics, billing, IAM roles, and multiple examples. No output schema, but response tiers are described. Comprehensive for a complex tool with 6 required parameters.

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 100% already, but description adds layered meaning: explains response tiers (summary/detail/raw), lists supported services and action conventions, details session_id format and suffix, gives filter examples for metrics. Significantly enhances understanding beyond 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?

Clearly states 'Inspect GCP infrastructure' with specific verb 'inspect' and resource 'GCP infrastructure'. Distinguishes from sibling 'awsinspect' by being GCP-specific. Lists many services and actions, making purpose unmistakable.

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

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

Explicitly states prerequisite: requires prior deployment attempt and to check convostatus. Provides context for when to use (user asks about status/details). Does not explicitly list when not to use, but sibling tools imply alternatives. Clear usage guidance.

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

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

Beyond annotations (readOnlyHint, openWorldHint), description adds operational details: backend fetches credentials once, fans out probes with concurrency 8, 30s per-sub timeout, 60s wall clock, 512KB response cap, and partial failure behavior (credential fetch failure leaves cred-less probes succeeding). 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?

Well-structured with headers, bullet points, and warnings. Front-loaded key purpose. Some redundancy (subs schema repeated in examples) but overall efficient for the complexity.

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

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

Despite no output schema, description explains response format (ordered array with index/service/action/ok/result/error), truncation behavior, and partial failure. Covers prerequisites, limits, and examples. Complete for a batch inspection 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 100% so baseline is 3. Description adds value with examples showing subs array structure and session_id format, plus practical usage notes like warning about ?token= suffix. Extra context justifies a 4.

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

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

The description starts with 'BATCH INSPECTION: run up to 32 GCP inspect probes in one call', clearly specifying the verb (batch-inspect), resource (GCP infrastructure), and scope (up to 32). It distinguishes from sibling gcpinspect by contrasting batch vs singular.

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: 'Use this when you need to check more than ~3 resources', prerequisite check for hasDeployAttempt, and when not to use: 'For a specific service's actions, use gcpinspect (singular)'. Also warns about partial failure and not aborting on first error.

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 response structure: 'Responses include hints with next_actions and related_tools.' Annotations already indicate readOnlyHint=true and openWorldHint=true, so description adds useful 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?

Three concise sentences: first states purpose, second details usage, third describes response hints. No wasted words, front-loaded with key 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?

Complete information for a help tool: purpose, usage modes, section options, and response content (hints). No output schema needed as description explains return type. Covers all necessary context.

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 100% coverage for the single optional parameter 'section'. Description mentions the sections but does not add meaning beyond the schema's enum and description. 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?

Description clearly states 'Get workflow guidance for using InsideOut infrastructure tools.' and distinguishes from sibling tools by being a meta-guidance tool. It specifies the verb 'get' and resource 'workflow 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?

Explicit instructions: 'Call help() for a compact overview, or help(section=...) for a detailed guide.' Lists available sections, providing clear when-to-use guidance. Distinguishes from siblings which are specific infrastructure tools.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true. The description adds that the tool uses 'live IR via chat history' and that pending drafts are not used as the target, providing context beyond the 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 concise (a few sentences) with the main purpose stated first, followed by details on defaults and requirements. No 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?

Given 3 parameters (1 required), no output schema, and the tool's complexity, the description covers defaults, version behavior, and session requirements. Could be slightly improved with an example output but is sufficiently complete for tool selection.

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?

All parameters have schema descriptions (100% coverage). The description adds clarification on defaults (from_version defaults to last applied, to_version defaults to current draft) and the exact format of session_id, enhancing meaning beyond the schema alone.

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 specifies a 'structured diff showing what would be deployed', including component-level changes, field-level details, and pricing deltas. This clearly distinguishes it from sibling tools like stackversions (list versions) and tfplan (full plan).

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 default behavior (comparing last deployed vs current live design), explicit version arguments for arbitrary comparison, and the required session_id. It mentions the empty baseline scenario but does not explicitly state when not to use (e.g., if no deployment history).

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

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

Annotations indicate idempotent and non-destructive behavior. The description adds details: copies components/config/pricing, and updates draft in-place if it exists (single-draft rule). This aligns with annotations and provides behavioral context beyond them.

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

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

The description is concise: three sentences plus a usage note, front-loaded with the main action. Every sentence adds essential information without fluff.

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

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

Given no output schema, the description covers prerequisites, behavior, and parameter details. It could explicitly state what is returned (e.g., draft version ID), but overall it is sufficiently complete for a tool with good annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the session_id format and warning not to strip the token suffix, and clarifies that version is from stackversions. This provides useful semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a draft version by reverting to a previous version's config.' It specifies the verb (create), resource (draft version), and distinguishes it from sibling tools like stackversions (list versions) and stackdiff (diff).

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

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

The description advises using stackversions first to find version numbers and mentions required session_id from convoopen. This provides clear context on when to use the tool and prerequisites, though it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, so the agent knows it's safe. The description adds behavioral context: lists newest first, includes status and change summaries. It also mentions the required input format. No contradictions. The description provides useful behavioral details 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: three sentences plus a requirements line. It front-loads the primary purpose, then adds details and usage guidance. Every sentence adds value, with no redundancy or fluff.

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

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

Given that there is no output schema, the description adequately explains what the tool returns: version number, status, change summaries, timestamps. The single parameter is fully documented. Complexity is low, and the description covers all necessary context 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 coverage is 100% with a detailed description for session_id, including pattern and instruction not to strip token. The description reinforces that the session_id must come from convoopen and specifies the format. This adds significant value beyond the schema by explaining the source and handling.

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 'List all stack versions for a session (newest first)' using a specific verb and resource. It also lists the information included: version number, status, change summaries, and timestamps. This distinguishes it from sibling tools like stackdiff (compares versions) and stackrollback (rolls back).

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

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

The description explicitly says 'Use this tool to see the design history, review what changed between iterations, or find a version number to roll back to.' This provides clear use cases. It also notes a prerequisite (session_id from convoopen). However, it does not specify when not to use or list alternatives, but given the narrow scope, this 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 openWorldHint=true and destructiveHint=false. The description adds behavioral details: it forwards feedback to the Luther Systems team, requires certain parameters, and explains the initiator field. There is no contradiction with annotations.

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

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

The description is well-structured with sections (FEEDBACK, REQUIRES, OPTIONAL, Categories, Initiator, Examples) and front-loaded. It is somewhat verbose but not wasteful. Minor redundancy (e.g., 'This includes...') prevents a perfect score.

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

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

Given 7 parameters, no output schema, and moderate complexity, the description covers all necessary aspects: parameter explanations, usage patterns, categories, initiator semantics, and examples. No gaps 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?

The input schema has 100% coverage (all 7 parameters described). The description adds value by listing required vs optional parameters, explaining the initiator field with examples, and detailing categories. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool is for submitting feedback, bug reports, or feature requests to Luther Systems. It distinguishes itself from sibling tools (none of which are feedback-related) and uses a specific verb-resource combination (submit feedback).

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 (forward user feedback or report agent-detected issues) and includes examples for both user and agent initiators. It does not explicitly state when not to use it, but the context is clear enough.

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

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

The description adds significant behavioral context beyond the annotations (destructiveHint, openWorldHint). It notes that the job runs 15+ minutes, enforces single-flight (only one TF job per session), returns a conflict job_id when blocked, and explains credential handling with connect_url and credawait. This fully informs the agent of what to expect.

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

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

The description is fairly long but well-structured: it starts with workflow context, then highlights critical notes (long-running, single-flight), followed by optional parameters and credential flow. Every sentence adds value, though some redundancy exists (e.g., repeating 'single-flight' in multiple places). Overall, it's efficient for the complexity.

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

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

Given no output schema, the description covers return values (confirmation, connect_url, conflict job_id). It includes all parameters, workflow steps, restrictions, and error handling. The credential flow is fully documented. An agent can use this information to correctly invoke the tool and handle 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?

With 100% schema coverage, baseline is 3, but the description enriches each parameter with usage context. For example, 'plan_id' is linked to the preview-then-apply workflow, 'sandbox' explains real vs test deployment, 'ignore_drift' clarifies when to use after reviewing drift, and 'force_new' describes the single-flight bypass. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: 'Deploy infrastructure by starting a Terraform job for an InsideOut session.' It also places it as 'Step 4 of 4' in a workflow, distinguishing it from sibling tools like tfplan, tflogs, and tfstatus. The verb 'deploy' and resource 'infrastructure' are specific, and the scope is well-defined.

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

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

The description provides explicit when-to-use (step 4 after file generation) and when-not-to-use (if another job is in flight, use tfstatus/tflogs). It offers alternatives like 'pass force_new=true' for wedged runs and details the preview-then-apply workflow using tfplan and tflogs. Credential flow is also outlined, guiding the agent on using credawait after showing connect_url.

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

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

The description adds significant context beyond annotations: it's a long-running job, single-flight behavior, return of tf_job_conflict, and post-destroy session state (hasDeployment set to false). Annotations only indicate destructiveness, so description carries full behavioral disclosure.

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

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

The description is well-structured with clear headings and bullet points, front-loaded with the purpose, and 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?

Despite no output schema, the description covers prerequisites, post-destroy state, monitoring references, and error handling (tf_job_conflict). It is complete for a destructive tool with these usage patterns.

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

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

Schema coverage is 100%, but the description adds critical meaning: session_id must be exact from convoopen with ?token= suffix, never stripped; force_new explained as bypass guard only when wedged. This goes beyond schema descriptions.

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

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

The description explicitly states the tool's purpose: 'DESTROY: Tear down previously deployed infrastructure' and specifies it calls the Oracle destroy endpoint. It clearly distinguishes from siblings like tfdeploy and tflogs.

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

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

The description provides explicit when-to-use guidance (after successful deployment, requires session_id) and when-not-to-use (single-flight conflict). It names alternatives (tfstatus/tflogs for monitoring) and conditions for force_new override.

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 discloses read-only/non-destructive nature (matching annotations), single-flight conflict return, and drift detection outcome handling. Adds context beyond annotations, e.g., that force_new should be used only when the current run is provably wedged.

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 moderately long but well-structured with bold headings and bullet points. Every sentence adds value, though it could be slightly more concise. Front-loaded with purpose and key constraints.

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

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

Despite no output schema, the description explains the return value (job_id) and how to retrieve results (tflogs). It covers all prerequisites, constraints (single-flight), and post-drift actions. For a two-parameter tool, this is thoroughly complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaningful guidance: for 'force_new' it explains when to use (bypass single-flight guard when wedged), and for 'session_id' it emphasizes exact formatting and retaining the token suffix. This exceeds schema-only info.

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 deployed infrastructure against Terraform state. It distinguishes itself from sibling tools (e.g., tfdeploy, tflogs) by focusing on drift detection only.

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 (detect drift), when-not-to-use (single-flight constraint, force_new only if wedged), prerequisites (session_id from convoopen, prior deployment with project_id), and alternatives (tflogs for streaming, tfdeploy with ignore_drift to proceed).

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 idempotency and non-destructiveness. The description adds many behavioral details: default response returns summary+download URL, fallback with include_code, session_id format requirement, and the critical workflow. No annotation contradiction. Slightly lacking on error handling for invalid sessions.

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

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

The description is longer but well-structured with sections (WORKFLOW, PREREQUISITE, etc.) and front-loaded with purpose. Each section adds necessary workflow context. Could be slightly more concise, but the structure aids comprehension.

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

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

The description is comprehensive for a multi-step workflow tool: it covers prerequisites, default response, fallback, critical workflow steps, and post-generation actions. No output schema, but the description explains the default representation. All relevant context is provided.

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

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

Schema coverage is 100%, but the description adds important context: session_id must include the '?token=' suffix and never be stripped, and include_code is a fallback for sandbox issues. This adds clear semantic guidance 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 is 'Step 3 of 4' and 'Generate Terraform files from completed design'. It distinguishes from sibling tools by specifying it is part of the InsideOut workflow and requires terraform_ready=true from convoreply, which is unique among the sibling list.

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 call (after convoreply returns with terraform_ready=true) and when not to (while convoreply is running). Provides a step-by-step critical workflow and mentions post-generation steps, but does not explicitly contrast with sibling tools like tfplan or tfdeploy.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds substantial behavioral context: different modes for running vs completed jobs (REST vs SSE), timeout-based pagination for running jobs, response fields including complete flag, and a warning about context window. No contradiction with annotations.

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

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

The description is well-structured with clear sections (MONITORING, PAGINATION, RESPONSE FIELDS, REQUIRES/OPTIONAL, CONTEXT WARNING). It is concise, every sentence adds value, and the most critical information (purpose and required parameter) appears first.

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

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

Despite lacking an output schema, the description thoroughly explains response fields (logs, last_event_id, complete, total_logs). It covers both running and completed job scenarios, pagination mechanics, and potential issues like context window overload. No gaps for a log-fetching 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?

All 5 parameters have schema descriptions (100% coverage), but the description adds extra value: session_id includes a critical warning about preserving the ?token= suffix, tail is recommended for completed jobs, and last_event_id is explained in the pagination flow. This goes beyond the schema alone.

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 pagination, distinguishing it from sibling tools like tfruns (which lists runs) and tfstatus (which shows status). It uses a specific verb ('Fetch') and resource ('Deploy Logs'), and the MONITORING heading reinforces the purpose.

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

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

The description provides explicit guidance on when to use pagination, how to paginate with last_event_id, and the required session_id from convoopen. It also recommends using tail:50 for completed jobs to avoid context overload, and mentions optional job_id from tfruns. This covers both when and how to use the tool effectively.

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, but the description adds valuable detail: sensitive outputs are redacted, default returns latest deploy, and job_id/lifecycle behavior. It does not contradict annotations.

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

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

The description is well-structured with clear sections (INSPECTION, Returns, Sensitive, By default, REQUIRES, OPTIONAL). Every sentence adds value with no redundancy. It is appropriately sized for the tool's complexity.

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

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

No output schema exists, so the description explains that outputs are structured values like VPC IDs and endpoints, and mentions redaction. It covers the main aspects but lacks detail on error handling or empty results. Overall, it is fairly complete for a simple inspection 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 100%, baseline 3. The description adds meaning beyond the schema: it explains that job_id fetches outputs from a specific deployment, lifecycle filters by deploy step, and session_id must include the token suffix and not be stripped. This provides practical guidance.

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 retrieves Terraform outputs from a completed deployment, using specific verb 'Retrieve' and resource 'Terraform outputs'. It distinguishes from sibling tools like awsinspect and gcpinspect by focusing on deploy outputs with structured values like VPC IDs and endpoints.

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

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

The description explicitly requires session_id from convoopen and optionally job_id and lifecycle, providing clear context for when to use. It labels the tool as 'INSPECTION', indicating read-only purpose. However, it does not explicitly state when not to use or compare to other tools for 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?

Adds significant context beyond annotations: single-flight, return values (job_id, plan_id, project_id), conflict handling, and credential requirements. Annotations already indicate idempotent and non-destructive.

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, front-loaded with 'PREVIEW', each 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?

Covers all aspects: prerequisites, behavior, error handling, return values, and references related tools. No output schema, but return info is stated. Complete for a plan 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?

Description explains each parameter in detail: sandbox (testing), force_new (bypass guard), session_id formats and warnings. Schema coverage is 100% but description adds meaningful usage context.

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

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

The description clearly states the tool previews infrastructure changes by running terraform plan without applying, using specific verbs and resource. It distinguishes from siblings like tfdeploy and tfdestroy.

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 to use before tfdeploy, mentions tflogs for streaming and force_new for wedged runs. Also states prerequisites and single-flight guard.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's 'INSPECTION' label and privacy of session-scoped results are consistent but add limited new behavioral context. No contradictions, but the description does not disclose additional traits like rate limits or auth details beyond the session token requirement.

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 highly concise: a one-line purpose header ('INSPECTION: List all Terraform deployment runs for a session'), a sentence on return data, a sentence on use cases, and a brief prerequisite. No wasted words; front-loaded effectively.

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

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

For a tool with one required parameter, no output schema, and annotations covering read-only and open-world, the description is largely complete. It covers purpose, return data, and usage guidance. The only minor gap is not explicitly stating that results are scoped to the session, but that is implied by the single parameter.

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 (100% coverage) already describes the session_id parameter with pattern and notes. The description adds valuable usage guidance by emphasizing to pass the ID EXACTLY as returned, including the '?token=...' suffix, which is crucial for correctness and not clear from schema alone.

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

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

The description clearly states the action (list runs) and resource (Terraform deployment runs for a session), and specifies the returned data (job IDs, statuses, types, timestamps). It effectively differentiates from sibling action-oriented tools like tfdeploy 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?

The description provides explicit use cases ('see deployment history, find job IDs for log inspection, or check which deployments succeeded or failed') and mentions a prerequisite (session_id from convoopen). It does not explicitly state when not to use it or suggest alternatives, but the context makes it clear, earning a 4.

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

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

Annotations are readOnlyHint=true and openWorldHint=true; description adds detailed behavioral context about two timestamps (updated_at vs last_refresh_at) and their significance, which is 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?

Description is somewhat lengthy but well-structured with headings, each sentence adds value; could be slightly more concise but still efficient.

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

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

No output schema, but description explains returns job status, job_id, metadata, and two timestamps; sufficient for a monitoring tool with good annotations.

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

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

Schema coverage is 100% with descriptions; description adds critical context: session_id must include ?token= suffix, job_id is optional and can be found via tfruns, and warns not to strip the token suffix.

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

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

The description clearly states it checks deployment status (running/completed/failed), distinguishes from tflogs (stream logs) and tfruns (discover IDs), and specifies it returns metadata without streaming logs.

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

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

Explicitly says to use for quick status check, names alternatives tflogs and tfruns, and provides requirements (session_id, optional job_id) with format details.

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