StewAI

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds 'deterministic' and 'free', which are consistent with annotations. It does not mention any side effects, error handling, or return behavior, but annotations cover the safety profile. It adds moderate value by clarifying deterministic and free nature.

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

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

The description is a single, concise sentence that front-loads the purpose and includes a conditional usage note. No filler words; every clause adds information. It is appropriately sized.

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

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

The tool has 3 parameters, an output schema, and annotations. The description covers the core purpose and the fixtures parameter, but misses usage guidance relative to siblings and explanations for build_ref and render_only. Given the complexity (multiple check types, fixture mode), the description is incomplete for an agent to correctly invoke the tool without further inference.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only explains the fixtures parameter in detail (how to use it and the requirement to provide upstream dependency values). It does not explain build_ref (what it is, its purpose) or render_only (whether it limits to rendering only). This is a significant gap since the schema provides no descriptions.

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

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

The description clearly states it runs lint, render, policy, and compiler checks on a recipe build. The verb 'run' and the specific check types distinguish it from sibling tools like run_recipe or get_recipe_build. It is specific and unambiguous.

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

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

The description gives instructions on how to use fixtures ('Omit fixtures for the normal structural check; a supplied fixture probe must also provide every referenced upstream dependency value') but does not explicitly state when to choose this tool over siblings. It implies it's for pre-run validation but doesn't mention alternatives like review_recipe_build or run_recipe. This is a gap.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful behavioral constraint with 'bounded, disclosure-safe view,' though this phrasing is vague about what exactly is bounded or hidden.

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 a single, front-loaded sentence with no filler or redundancy. It is concise, though the 'disclosure-safe' phrasing is imprecise and could be more concrete without adding 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?

Despite having an output schema and helpful annotations, the description leaves important operational context unexplained: what a 'batch' is, how cursor pagination works, what each section means, and when polling is appropriate. This is too thin for a tool with three parameters including a complex enum.

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

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

Schema description coverage is 0%, so the description must compensate for the schema's lack of parameter documentation. It does not mention activity_ref, cursor, or section, nor does it clarify how the section enum affects the returned view. The description adds almost no meaning beyond the parameter names themselves.

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 uses a specific verb ('Poll') and identifies a bounded view of recipe build activity, which distinguishes it from sibling tools like get_recipe_build or check_recipe_build. The phrase 'review or acceptance batch' is somewhat jargon-heavy, but the title and action make the core purpose clear.

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?

No guidance is given about when to use this tool instead of siblings such as check_recipe_build, review_recipe_build, or get_recipe_build. The word 'Poll' implies repeated monitoring, but there is no explicit context, exclusions, or alternative routing.

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 idempotentHint=true, so the description adds meaningful behavioral context: pagination via next_cursor until null, concatenation of content fragments in offset order, and decoding of JSON sections after completion. It also discloses that opaque internals remain withheld, which goes beyond the annotations.

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

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

The description is compact and front-loaded with purpose, then provides operational details. Every sentence earns its place, though the jargon-dense phrasing ('bounded method and limitations excerpts') slightly reduces clarity.

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

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

An output schema is present, so return-value details are covered. The description supplies pagination, assembly, and view-mode mechanics needed to invoke the tool correctly. A minor gap is the lack of a stated default for the optional view parameter and no definition of 'safe summary'.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain cursor usage ('Use next_cursor with the same recipe_ref until null') and the view enum's purpose, but recipe_ref semantics are only implied by the tool name, and cursor formatting is not specified. Meaningful but incomplete compensation.

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 action ('Inspect') and a specific resource ('a safe summary with bounded method and limitations excerpts, output-contract state, and evidence context'). It clearly identifies the tool as a preview mechanism, though it does not explicitly distinguish it from sibling tools like get_recipe_build or search_recipes.

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 gives internal mode guidance ('use view=details' for complete details) but offers no guidance on when to choose this tool over sibling alternatives. It does not state exclusions or when-not-to-use, leaving the agent without tool-selection context.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior, and the description adds meaningful operational context: status requires run_id, the distinction between updated_at and progress.last_step_activity_at, and the credit_pause signal for blocked runs. This goes beyond simply restating the annotations.

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

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

The description packs all essential behavior into two dense sentences with no filler, and the most important purpose is front-loaded. The second sentence is long and technical, but every clause contributes; it could be split for readability without gaining 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?

For a 6-parameter tool with three views, an output schema, and read-only annotations, the description covers the conditional requirements, view semantics, timestamp distinction, and a special blocked-run state. It does not describe pagination semantics or error behavior in depth, but the output schema and annotations fill the main remaining 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 description coverage is 0%, so the description must carry parameter meaning. It maps view values to use cases and notes that default status requires run_id, and it lists recipe_ref/status/cursor/limit as the history-view parameters. However, it never explains what cursor/limit/status/recipe_ref mean or how they interplay, leaving the agent to infer from names and schema constraints.

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

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

The description opens with 'Read an owned run' and then defines the three views (status/history/diagnostics) with distinct purposes, so the operation and resource are explicit. It clearly separates get_run from the recipe-build sibling tools by focusing on owned run states and resumption.

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

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

It provides concrete when-to-use guidance: view=history for resuming normal runs with recipe_ref/status/cursor/limit, view=diagnostics for the settled UI receipt, and default status for live progress with run_id. It does not name sibling alternatives or give explicit when-not-to-use conditions, so it stops short of 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 cover idempotency and non-destructiveness, so the description only needed to add contextual behavior. It does add 'bounded' and 'exact private draft revision', which give some useful scoping beyond the annotations. However, it does not clarify what actually happens in 'quote' mode versus 'execute' mode, or whether executing a review writes any state to the revision.

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 a single sentence with no filler, and the primary mode distinction is front-loaded. It is appropriately concise, though the brevity comes at the cost of missing substantive guidance captured in other dimensions.

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 four-parameter tool with zero schema description coverage, the description is too sparse. Although an output schema exists, the agent still lacks enough context to understand what quote vs. execute yields, what the idempotency key is for, or when this tool should be selected among twelve siblings. It is minimally viable at best.

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

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

Schema description coverage is 0%, so the description needed to explain the four required parameters. It only loosely covers 'revision' and 'build_ref' via 'exact private draft revision', and it merely echoes the 'mode' enum with 'Quote or run'. It provides no meaningful semantics for 'idempotency_key' and no parameter-level 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 states a specific action ('Quote or run') and a concrete scope ('a bounded semantic quality review of the exact private draft revision'). It is not a tautology and gives the agent a sense of what the tool operates on. However, it does not explicitly distinguish itself from sibling tools like 'check_recipe_build', and the phrase 'bounded semantic quality review' is somewhat jargon-heavy.

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?

There is no explicit guidance on when to use this tool versus alternatives. Sibling names like 'check_recipe_build', 'commit_recipe_build', and 'update_recipe_build' suggest related workflows, but the description never says why an agent should choose 'review_recipe_build' over them. The only implicit context is that it targets a 'private draft revision'.

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

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

Annotations already indicate readOnly=false, openWorld=true, idempotent=true, and destructive=false, but the description adds valuable non-obvious behavior: quotes expose acceptance_cost enforcement bounds, supervised_required is returned before any side effect, and external approval is needed via action_url. No contradiction with annotations exists.

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 main action is front-loaded in the first sentence, and subsequent sentences carry dense, relevant workflow information. The approval sequence is long but justified by complexity; there is no filler, though it could be slightly tightened.

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 covers modes, quote semantics, budget requirements, and the supervised approval flow, which is strong for a complex tool with an output schema and annotations. It does not explicitly define build_ref or idempotency_key, but the agent has enough context to call the tool correctly in most cases.

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 description partially compensates for the low 20% schema coverage by explaining mode-related intent ('Quote or run selected or complete') and the revision target, but it leaves build_ref and idempotency_key semantically unexplained. Since these are required parameters and the schema gives them no descriptions, there is still a meaningful gap.

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

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

The opening sentence states a specific verb, resource, and scope: 'Quote or run selected or complete behavioral acceptance cases for an exact private draft revision.' It clearly distinguishes quote mode from run mode and names the sibling update_recipe_build for the approval workflow, so an agent can tell this tool apart from generic run_recipe.

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 gives actionable context: quote vs. run, the paid-work budget prerequisite, and an explicit supervised_required flow using update_recipe_build bind_resource and resume_activity. It also tells the agent to bind required resources before opening action_url, which is concrete sequencing an agent can follow.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details beyond these: it explains the distinction between direct fits and related_results, discloses that each row includes output contract and cost history, and clarifies that safety review is not output-quality validation. It also specifies the exact-matching semantics for required inputs/outputs and the pagination protocol. This is rich, non-redundant transparency.

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

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

The description is a tight, front-loaded paragraph of four sentences. It leads with the primary purpose, then covers output semantics, row contents, matching rules, and paging in a logical order. Every sentence earns its place; there is no fluff or repetition. This is exemplary conciseness.

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

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

Given the tool's complexity (6 parameters, an output schema, and a rich result structure), the description is remarkably complete. It explains the output fields (results vs. related_results, row contents), the matching rules, and the pagination contract. The output schema is present, so detailed return formatting is not required, but the description still provides a high-level contract. Nothing an agent needs 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 83%, so the schema already documents each parameter thoroughly. The description reinforces the matching semantics for required_inputs and required_outputs, and the paging behavior, but it adds little new meaning beyond what the schema descriptions already state. It does clarify the overall contract (direct fits vs. related_results), which indirectly aids parameter understanding, but the marginal value over the schema is limited. 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 opens with a specific verb and resource: 'Find safe public recipes and published recipes available to the current account.' It further distinguishes itself by explaining the result structure (direct fits vs. related_results) and by its focus on search, which is unique among the sibling tools that manage builds and runs. This clearly states what the tool does and sets it apart.

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 gives clear context for using the tool: it is for searching recipes and explains how to handle pagination (repeat with cursor) and how to phrase queries (add constraints via required_inputs/required_outputs). It does not explicitly list when to prefer alternative tools, but the purpose is obvious from the domain and sibling names. No exclusion guidance is provided, but the context is sufficient for a competent agent.

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

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

The description adds real value beyond the annotations: it discloses that the response returns stored contracts only when they fit the bounded result, that the archetype bundle is optional guidance rather than the build contract, and that richer input constraints must be handled in recipe logic and tested rather than claimed as enforced. This behavioral context is not signaled anywhere in the structured annotations and is genuinely useful. No contradiction with annotations (idempotentHint=true aligns with the idempotency-related context, readOnlyHint=false matches the create operation).

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 dense but purposeful, front-loading the purpose in sentence one and adding behavioral and constraint context in the following sentences. It's longer than ideal but every sentence earns its place, covering response semantics, constraint enforcement, and the source-adaptation option.

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?

This is a complex tool (10 params, 9 required, nested objects, 2 enums) and the description covers the most important semantics well, including response behavior and input constraint philosophy. But it leaves the enums (quality_profile, research_policy, capabilities, risk_domains) and the idempotency_key contract unexplained, relying on the output schema and agent inference to fill 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 0%, so the description carries the burden. It partially compensates by explaining source_recipe_ref's purpose and setting input string constraint norms (type:string, positive maxLength, minLength:1 only on required inputs). However, it does not address several key parameters (idempotency_key semantics, quality_profile, research_policy, capabilities, risk_domains), leaving the agent to infer or open the schema for those.

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 'Create a private recipe build from a bounded intent and declared contract' gives a specific verb, resource, and scope, and the 'private draft' wording helps distinguish it from update/commit siblings. However, it doesn't explicitly name which siblings it is not (e.g., update_recipe_build, commit_recipe_build), leaving some differentiation to inference.

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 implies when to use it (creating a new private draft) and explains the optional source_recipe_ref for adapting owned or public-open recipes, which is genuinely useful routing context. But it never explicitly states when NOT to use it or names alternatives like update_recipe_build or review_recipe_build, so the guidance is implied rather than explicit.

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 destructive/idempotent/openWorld at a generic level, but the description adds operation-specific behavior the annotations cannot: set_contracts 'changes the revision and invalidates qualification', each handoff control op must be the only op in its request, and begin/append do not bump the revision while commit does once. Duplicate-work risk from a new idempotency key is also spelled out.

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?

Given a 15-op polymorphic schema, a long description is defensible, and the purpose is front-loaded. But it is a single unstructured block, and the idempotency replay sentence ('After an uncertain response, inspect the build and replay the identical request with the same idempotency key...') is repeated verbatim at the start and end, so not every sentence earns its place.

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

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

The return format need not be described because an output schema exists, and the description still covers the hard parts of a complex mutation tool: concurrency via revision+idempotency key, size limits and chunking, handoff sequencing, and assertion/suite shapes. Minor gaps remain for a few op variants and the meaning of build_ref, but nothing an agent needs to avoid a destructive mistake 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 0%, and the schema is a 15-branch oneOf, so the description carries real weight: it names set_metadata/metadata, upsert_schema/schema_id+schema, set_acceptance_cases/suite, set_contracts, and the chunk ops, and gives literal suite/fixture/assertion examples with the paired-vs-scalar pair_case_id distinction. It still leaves replace_spec, upsert_node, remove_node, reorder_nodes, remove_schema, restore, record_research, set_budget, and build_ref/revision semantics unexplained, so the compensation is substantial but incomplete.

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+resource+scope: 'Apply bounded optimistic changes to an owned private recipe build', which tells an agent this is the mutation entry point for a draft build. It does not, however, explicitly contrast itself with siblings like commit_recipe_build, review_recipe_build, or run_recipe, so the agent must infer the draft-vs-commit boundary.

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 routes the agent explicitly: replay with the same idempotency key after an uncertain response, use get_recipe_build with specific view/schema_name values to resolve unknown ops, use begin/append/commit_chunk for large content, use bind_resource then resume_activity/cancel_activity for handoff, and never invent set_schema/set_acceptance_suite. These are concrete when-to-use and when-not-to rules, not inference cues.

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