ChatStack - App Cost Estimator

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

Annotations already declare readOnlyHint/destructiveHint=false, so the bar is lower, yet the description adds real behavioral context: the read is non-advancing, post-submission calls return post_submit_notice and post_submit_links, and the notice must be relayed verbatim with URLs preserved. It still omits failure behavior (expired/invalid handle) and whether reads are idempotent across polls.

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 action and scope, then output behavior, then input provenance, then exclusions. Four dense sentences with no filler, though the 'do not add an email-delivery caveat' instruction is idiosyncratic and sits awkwardly mid-paragraph.

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 annotations cover the safety profile. The description still supplies the things structured fields cannot: non-advancing semantics, post-submit handling rules, input provenance, and explicit non-uses.

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 both params are documented at the source, so the schema does the heavy lifting. The description adds only a mild locational hint ('from the Session section') and otherwise restates that both values must be passed; 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 ('Read the current app cost estimate') plus a crucial scope qualifier ('without advancing it'). It also implicitly distinguishes itself from the mutating siblings (submit_prd, send_action) by naming what it must not be used for.

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 excludes two wrong paths: 'Do not call start_session to recover a session' and 'do not use this tool to approve, edit, or submit.' Combined with 'read without advancing,' an agent knows exactly when this tool applies and which sibling to pick instead.

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 declare non-read-only, non-destructive, closed-world; the description adds what actually happens: one call per result, re-call only while next_tool is send_action, an approve advances exactly one phase, and reject actions re-display the current table and wait. It also covers the auto-complete path's receipt/pipe-table behavior and the instruction not to ask for approval.

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 and the required-input rule are front-loaded, and nearly every sentence carries a routing or formatting constraint. It is dense and full of chained conditionals that would read better as a short list, but there is no filler.

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

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

For a stateful widget-submission tool with an output schema and nested payload, it covers mode differences, the next_tool handoff, rejection loops, and the exact answer format. Nothing an agent needs in order 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 80%, but the description still adds meaning the schema lacks: action_type must come from allowed_actions, action_type and payload are omitted in auto-complete, confirmed_by_user is preferred but not a substitute, and payload.answers must be keyed by question id with letter-only values like {"q1":"A"}. That last example directly disambiguates a nested-object parameter the schema leaves as untyped additionalProperties.

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 opening sentence states a specific verb and resource ('Submit the user's pending choice') and immediately narrows the action_type source to pending_gate_payload.allowed_actions. It explicitly distinguishes itself from siblings by naming send_turn and submit_prd and describing the handoff conditions.

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 spells out both modes: in Review each step action_type is required, in Run it for me omit action_type and payload. It names the alternative (send_turn with interaction_mode) and the exact cases where mode_select_* must not be used, and tells the agent to stop and offer submission when next_tool is submit_prd.

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 declare readOnly=false, destructive=false, openWorld=false, so the description adds real value: it discloses a hidden side effect (phrases like 'Run it for me' inside input_as_text silently switch the thread to auto_complete) and a server default (clarify_first is accepted when interaction_mode is omitted). It does not describe the response shape, but an output schema exists, so that omission is acceptable.

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?

Content is largely load-bearing, but the interaction-mode guidance is restated almost verbatim ('In interaction mode Review each step...' appears twice), and the unquoted enum-style phrasing ('Review each step', 'Run it for me') is dense to parse. The core instruction to pass exact words is front-loaded, but tightening would materially help readability.

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 4-parameter mutation-ish tool with an output schema and full annotation coverage, the description covers the awkward part — thread mode handoff and verbatim input handling. Only minor gaps remain, such as what happens to the table/decision receipt on the next turn, which the output schema presumably covers.

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, and the description earns above that by adding omission semantics the schema only hints at: omit input_as_text *only* when the reply is just the mode, and omit interaction_mode when no mode is set yet. It also clarifies that compact replies like '1A, 2B' are valid verbatim input.

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?

Opens with a specific verb+resource ('Continue an app cost estimate') and enumerates exactly what payload it carries: answers or scope changes to MVP scope, user stories, requirements, or tech spec. It also explicitly carves itself away from siblings ('Do not use send_action or mode_select_* for that choice'), so an agent can route correctly 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?

Gives when-to-use (sending user answers or requested changes), when-not (mode selection alone goes elsewhere; do not use send_action or mode_select_*), and explicit fallback behavior when no mode has been chosen yet. It also branches guidance by interaction mode ('Review each step' vs 'Run it for me'), which is precisely the decision an agent needs to make.

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 say this is a non-read-only, non-destructive, closed-world call; the description supplies the real behavioral context: no portal account or token is needed, the call can return interaction_mode_question to prompt the user, and the text result carries a Session section with thread_id and interview_handle that must be copied into later tools. That is material state-handoff information an agent could not infer from 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?

Purpose is front-loaded in the first sentence and the operational rules follow in a logical order. There is some redundancy — 'Do not choose an interaction mode on the user's behalf' and the closing 'Preserve an explicitly selected mode without asking the user to choose again' restate the same rule — and the clause 'unless the user already named Review each step' is grammatically truncated, slightly slowing parsing.

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 still covers the important dynamic parts: the conditional question turn, the handle propagation, and mode persistence. The one soft spot is that the conditional trigger is described only loosely ('If interaction_mode_question is returned'), and the truncated mode-selection clause leaves a small ambiguity 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 coverage is 100% and the enum is documented inline, so the schema already carries the definition. The description still adds decision semantics the schema lacks: omit it by default, set it only when the user explicitly named a mode, and never infer auto_complete from a request for speed.

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 and outcome set: start a guided session to estimate app development cost, scope an MVP, and generate a software PRD. That is clearly distinct from the siblings (get_estimate_status, send_turn, submit_prd), and the follow-on reference to send_turn reinforces where this tool sits in the flow.

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 the default invocation (no arguments), the two exceptions that justify passing interaction_mode, and a hard when-not: do not pick a mode on the user's behalf, since wanting an estimate or a fast answer is not auto_complete. It also scripts the interaction_mode_question branch, including which option is the default and that the agent must wait before send_turn.

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 destructiveHint=true and openWorldHint=true, and the description is consistent with that while adding substantial detail the annotations cannot convey: it emails the pack, creates a portal project, requires telling the user beforehand, requires showing contact values for confirmation, relays post_submit_notice verbatim, and defines a strict success criterion (a ### PRD submitted receipt with project_id and version_id) while treating timeout or missing next_tool as failure. It also adds an idempotency guard against re-calling after a receipt.

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 purpose, then proceeds through preconditions, confirmation flow, success criteria, and retry limits in a workable order. It is dense and a few sentences are grammatically broken ('Run it for me stops at this tool', 'Do not submit it the way an empty send_action advances a milestone'), which costs some parseability, but almost every sentence carries an operative rule.

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, yet the description still defines exactly what a success receipt looks like and what to do when it is absent. For a destructive, open-world, 10-parameter submission tool with a human confirmation gate, nothing an agent needs in order 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% and the field descriptions already say 'suggested or confirmed' and 'set true only after the user confirms,' so much of the parameter guidance is restated. The description still adds non-schema rules that change invocation behavior: omit contact arguments the thread already collected, never invent a contact field, ask only for missing fields, and pass thread_id and interview_handle from the Session section.

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 compound resource: submit the completed PRD and app estimate for email delivery and portal project creation. It also distinguishes itself from siblings by naming get_estimate_status as the fallback check and by warning against the empty send_action milestone advance, so an agent can tell the three apart 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 precondition (only after user stories, requirements, tech specs, and the estimate exist), an explicit refusal path (if they decline, do not call this tool), and an explicit alternative when the outcome is ambiguous (call get_estimate_status). When-to-use, when-not-to-use, and the alternative are all present.

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