Tessryx

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

The description discloses that hypothetical mode runs 'WITHOUT changing anything' and explicitly says 'nothing is changed — this is a preview', which is consistent with readOnlyHint=true and destructiveHint=false. It also adds non-obvious behaviors: incomplete_nodes are runtime-built references that cannot be statically checked, and non-root subjects are analyzed without reachability weighting.

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 densely useful, with the core purpose front-loaded and examples inline. Minor redundancy exists ('WITHOUT changing anything' and later 'nothing is changed — this is a preview'), but the length is justified by 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?

For a tool with an output schema, the description still covers the essential return semantics (findings, deployable, incomplete_nodes), parameter syntax, and the non-root subject behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, and the description adds meaning on top: bare slugs mean @published, custom_domain expects a hostname, and hypothetical defines delete/unpublish/publish semantics with concrete examples. This materially improves an agent's ability to pick correct values.

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 a specific action ('Check whether a resource and everything it depends on is sound') and names the deployability outcome (errors/warnings/deployable), making the tool's job unambiguous. However, it never explicitly distinguishes this from sibling tools like get_resource_graph or validate_workflow, so the differentiation is left 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?

It gives explicit when-to-use guidance: run it before deleting or unpublishing something that other resources may use, and before publishing a draft to see whether it resolves. It does not name alternatives or state when not to use the tool, so it stops short of full when/when-not coverage.

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?

With only openWorldHint and destructiveHint annotations, the description carries most of the behavioral burden and handles it well: it discloses that this operation mints a new template plus version 1, that publish=true publishes in the same step, and that iteration should happen before wiring into a workflow. It could more explicitly state the unpublised-draft default, though the schema already covers that.

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 the tool's core purpose, then proceeds through the essential workflow and the key sibling distinction. Every sentence earns its place, and the parenthetical alternative is cleanly separated.

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 rich input schema, output schema, and focused workflow guidance, the description is complete enough for correct tool selection and invocation. It covers prerequisites, iteration, publishing behavior, and the main alternative tool without requiring the agent to infer the critical steps.

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

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

Schema coverage is 100%, so the schema already documents the parameters. The description adds useful semantics beyond the schema by explaining that the definition must be authored against get_api_template_definition_schema, that execute_api_template is the iteration path, and that publish=true collapses create-then-publish into one step.

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

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

The description states a specific verb ('create') and a specific resource ('a BRAND-NEW api template') and clarifies it mints the template plus its version 1. It distinguishes itself from create_api_template_version by explicitly saying that tool is for adding versions to existing templates.

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 a clear creation workflow: fetch the JSON Schema, author the definition, iterate with execute_api_template, publish with publish=true. It also names the exact alternative for appending versions to existing templates, so the agent knows when not to use 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?

Annotations only mark the operation as non-open-world and non-destructive; the description adds meaningful behavioral context: it evolves an existing template, creates an unpublished draft by default, and can publish immediately with publish=true. It stops short of disclosing error/auth/validation outcomes, but the schema describes that the owning service validates on submit.

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

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

Three sentences, front-loaded with purpose, followed by actionable guidance and a clear alternative. Every sentence earns its place with no redundant phrasing.

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 output schema exists, the description sufficiently covers the workflow: prerequisite (existing template), definition authoring path, publish behavior, and sibling differentiation. Nothing essential for selecting and invoking this tool is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters; the description nevertheless adds value by telling the agent to author the definition against get_api_template_definition_schema and to pass publish=true for immediate publishing. This goes beyond bare parameter names.

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 resource (api template version) and the specific action (add a new version to an EXISTING api template by template_id), and distinguishes it from create_api_template by explicitly directing brand-new template creation to that sibling. This is a specific verb+resource statement with sibling differentiation.

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 states the exact condition for use (existing template), how to author the definition (against get_api_template_definition_schema), the optional publish=true behavior, and names the alternative tool for brand-new templates. This is explicit when-to-use and 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 only carry openWorldHint=false and destructiveHint=false, so the description carries the behavioral burden — and it carries it thoroughly. It discloses the minting behavior (app + version 1 created together), automatic member capture via prefix rules ('you never hand-add members'), and the side-effect of publish=true. It also reveals the validation rule that an empty definition is draft-valid but unpublishable, which no structured field communicates.

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 core purpose is front-loaded in the first sentence, with publish behavior and sibling routing following logically. It runs long, but every clause contributes — workflow, membership semantics, schema reference, draft rule — with no filler or repetition of schema content. Slightly dense but appropriately so for a tool with a nested definition object.

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

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

With an output schema present, return-value explanation is unnecessary. The description covers the invocation workflow, definition schema lookup, publish semantics, validation constraints, and sibling alternatives. Nothing an agent needs to correctly select and invoke this tool is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds genuine meaning on top: slug becomes the folder prefix that drives automatic membership ('storefront/page, storefront/products…'), and definition is disclosed as holding the membership selector (prefix rules + includes/excludes). publish=true gains workflow context as 'publish v1 immediately'. It adds little for display_name/description, but those are self-explanatory.

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

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

The description opens with a specific verb+resource: 'create a BRAND-NEW app (mints the app + its version 1)'. It explicitly differentiates itself from its closest sibling with '(To add a version to an existing app, use create_app_version.)', and the slug-as-folder-prefix explanation further separates it from API-template/workflow creators. An agent can tell exactly what this tool produces and how it differs from similar tools.

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?

States when to start here — 'Start here when building a page or an API bundle' — and names the exclusion: adding a version to an existing app goes through create_app_version. It also walks through the authoring flow (choose slug, author members under the prefix, fetch the definition schema) and clarifies draft-vs-publish behavior. This is explicit, actionable routing 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?

Annotations provide openWorldHint=false and destructiveHint=false but no readOnlyHint, so the description carries the burden of explaining the write behavior. It does so: the call mutates an existing app's selector/display, and "publish=true to make it the live manifest immediately" implies the previous version is superseded. This adds useful behavioral context beyond the structured annotations, though it stops short of spelling out the fate of the previously live version.

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 tight sentences with zero filler. The core purpose is front-loaded in the first sentence, the authoring workflow in the second, and the sibling disambiguation in the third. Every sentence earns its place, and the parenthetical about create_app is placed exactly where the agent needs it.

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 — versioning semantics, publish behavior, a nested definition object, and an output schema — the description covers the essentials: purpose, definition authoring path (get_app_definition_schema), publish mechanics, and alternative routing. Minor gaps remain (whether the prior live version is destroyed or demoted on publish, and how unpublished drafts are listed), but nothing that would block a correct call.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents app_id, publish, and definition thoroughly. The description adds modest extra framing — "membership selector (prefix rules, includes/excludes)" gives the definition parameter practical meaning, and "live manifest" sharpens the publish semantics. This is value-add but not substantial enough to push above baseline.

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 names a specific verb and resource — "add a new version to an EXISTING app (by app_id)" — and states exactly what the version changes: "membership selector (prefix rules, includes/excludes) or display." It explicitly distinguishes itself from the immediate sibling create_app ("For a brand-new app, use create_app"), and is also distinguishable from the other create_*_version siblings by naming its resource.

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 an explicit when-not with a named alternative: "(For a brand-new app, use create_app.)" It also gives workflow guidance for the main path — author the version definition against the schema fetched from get_app_definition_schema — and explains when to set publish=true versus leaving the draft unpublished. The agent can select and execute this tool without inference.

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

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

The description discloses key behavioral context far beyond the sparse annotations: that the claim alone grants nothing, that ownership must be proven, and that two DNS records are returned for the customer to add. This prevents an agent from assuming the domain is immediately active.

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 front-loaded with the primary action and the critical caveat, then moves into the customer-facing flow, then the parameter lifecycle note. Every sentence earns its place and none is wasted.

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

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

For a tool with one required parameter, high schema coverage, an output schema, and a clear stateful flow, the description covers the essential workflow: what the claim produces, what the customer must do, and what to call next. The presence of an output schema means return-value details do not need to be repeated.

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

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

Input schema coverage is 100%, so the baseline is 3. The description adds meaningful lifecycle context for slug_prefix and root_endpoint, noting they are optional here and usually set later with update_custom_domain, which is beyond the schema's static property 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 opens with a specific verb and resource: 'Claim a custom hostname for this tenant and generate its DNS challenge.' It clearly distinguishes this tool from verify_custom_domain and update_custom_domain by framing the action as a claim, not a completed setup.

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 names verify_custom_domain as the next step after DNS records are added by the customer, and update_custom_domain as the tool for setting slug_prefix/root_endpoint after verification. This gives the agent a clear when-to-use and sequencing rule versus alternatives.

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

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

The description highlights key behavioral aspects: the datafile must be bound to a schema, schema validation applies, property order is preserved, and publishing is a separate step. Annotations indicate non-destructive behavior (destructiveHint false), which aligns with the 'create' action. It does not mention auth or rate limits, but these are not critical for a 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 concise, consisting of two sentences that are direct and free of fluff. It front-loads the core purpose and then provides essential caveats (schema requirement, property order, publishing step) without unnecessary elaboration.

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 creation tool, the description covers the necessary workflow context: the prerequisite (schema), the creation action, and the follow-up (publish). It does not detail the output or error cases, but these are typically not required in a tool description. Overall, it provides sufficient 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?

The schema descriptions already cover all parameters (100% coverage), and the tool description adds context about the relationship between schema_id and json (schema validates the JSON, generates the human editor). It also reinforces the preservation of property order. While redundant with schema descriptions in some places, it adds meaningful workflow context, so it is above average.

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 new datafile holding a JSON object.' It uses a specific verb (create) and resource (datafile), and distinguishes it from sibling tools like create_schema or create_dynamic_endpoint by emphasizing the datafile-specific requirement of being bound to 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?

The description provides useful usage guidance: it specifies the prerequisite of having a schema ('author or pick one with the schema tools first') and the next step after creation ('Publish it with publish_datafile to serve it from the CDN'). It does not explicitly contrast with update_datafile, but the creation vs. update distinction is clear from the tool name and 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 only declare openWorldHint=false and destructiveHint=false, so the description carries the burden of disclosing side effects. It does so effectively: the call mints both the endpoint and its version 1, and the publish=true vs. unpublished-draft behavior is clearly stated. No description contradicts the annotations, so no contradiction flag. It stops short of disclosing prerequisites or reversibility, but the core behavioral surface is covered.

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

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

Four sentences, each earning its place: core action, definition-authoring guidance, publish semantics, and sibling routing. The most decision-relevant fact (brand-new vs. version-add) is front-loaded, and there is zero filler or repetition of schema content.

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

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

Given that an output schema exists (return values covered), the input schema is 100% documented, and the description covers the publish workflow, authoring flow, and sibling differentiation, the tool is nearly complete for an agent to invoke correctly. The only gap is unstated prerequisites — e.g., whether the referenced workflow version must already exist or be published before this call succeeds.

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 schema itself is unusually rich (slug's path-routing, :param placeholders, 404 semantics, authoritative content_type). The description still adds value beyond it by revealing the definition's internal content — binding to a workflow by versioned-slug reference plus a cache setting — which the schema does not state. The publish flag's one-step meaning is also reinforced.

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 leads with a specific verb and resource: 'create a BRAND-NEW dynamic endpoint (mints the endpoint + its version 1)'. It precisely scopes the operation as creating a new endpoint, which distinguishes it from dozens of create_* siblings, and the parenthetical clarifies it also mints version 1. This is far more specific than the title alone.

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 names the alternative: 'To add a version to a dynamic endpoint that already exists, use create_dynamic_endpoint_version.' It also distinguishes the publish path (publish=true now vs. publish_dynamic_endpoint later) and directs the agent to get_dynamic_endpoint_definition_schema for authoring. When-to-use and when-not-to-use are both explicit, which is essential given 70+ 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?

The annotations declare openWorldHint=false and destructiveHint=false, but do not establish that this is a mutating operation. The description adds valuable behavioral context: it creates a new version on an existing endpoint, and that publish=true takes the version live immediately. This goes beyond what annotations alone convey, though it does not discuss draft lifecycle details beyond implication.

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: it opens with the core operation, then covers the authoring source, publish behavior, and the key sibling exclusion in four short sentences. Every sentence carries useful operational guidance with 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?

Given the rich input schema, output schema presence, and annotations, the description covers the remaining contextual needs: distinguishing existing vs. new endpoint creation, pointing to the definition schema, and explaining the publish path. Nothing operationally critical is missing for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the publish=true purpose and points to the definition schema tool, but most of the actual parameter meaning is already fully documented in the input schema. The description adds only marginal value for parameter understanding.

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 precise action: 'add a new version to an EXISTING dynamic endpoint (by endpoint_id)' to evolve an existing endpoint. It explicitly contrasts with create_dynamic_endpoint for brand-new endpoints, so an agent can disambiguate from the sibling tool without opening its 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?

The description gives clear when-to-use guidance: use this when the dynamic endpoint already exists, and explicitly names the alternative for new endpoints ('For a brand-new dynamic endpoint, use create_dynamic_endpoint.'). It also tells the agent to author definitions against get_dynamic_endpoint_definition_schema and explains the publish=true shortcut.

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 sparse ({openWorldHint:false, destructiveHint:false}), so the description carries the burden and meets it: it discloses that the call mints two artifacts (the schedule plus its version 1), that publish=true activates firing, and that the workflow definition must reference a versioned-slug (published/latest). It does not cover auth prerequisites or failure behavior, but the creation and activation semantics are clearly stated and consistent with destructiveHint=false.

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 dense paragraph but front-loaded with the core purpose ('Schedule authoring — create a BRAND-NEW schedule') and every clause earns its place: mint semantics, definition anatomy, publish behavior, and sibling routing. It is slightly repetitive with the definition parameter's schema text, but not bloated.

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 complex tool with a deeply nested required parameter, an output schema, and several tightly related siblings, the description is complete: it says what artifacts are created, what the definition must contain, how to author it correctly, how publish/activation works, and exactly which sibling to use instead. Return-value explanation is unnecessary given the output schema.

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

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

Schema description coverage is 100%, setting the baseline at 3, but the description adds genuine value beyond the schema: it explains the internal anatomy of the required 'definition' object (versioned-slug ref, cron+IANA timezone vs. 'every N minutes/hours' interval, optional $input binding), which the schema does not describe. This compensates for the one nested parameter with the most ambiguity.

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: 'create a BRAND-NEW schedule (mints the schedule + its version 1)'. The 'BRAND-NEW' qualifier and closing parenthetical explicitly contrast with create_schedule_version for existing schedules, so an agent can distinguish this tool from its closest sibling 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?

Provides explicit when-to-use guidance: 'To add a version to a schedule that already exists, use create_schedule_version' names the exclusion condition and the alternative tool. It also explains the publish path alternatives (publish=true inline vs. publish_schedule later) and directs the agent to get_schedule_definition_schema before authoring the definition.

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 indicate openWorldHint=false and destructiveHint=false, so the description carries the behavioral burden. It transparently states the additive nature ('add a new version'), the publish=true activation behavior, and that the service validates the definition. It does not detail what happens to previously published versions, but this is adequately implied by the versioning model.

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, front-loaded with the core purpose, and contains no filler. Every sentence adds value: purpose, definition authoring, publish behavior, and sibling differentiation are all covered efficiently.

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, combined with a fully documented input schema and an output schema, gives the agent everything needed to call this tool correctly. It covers what to pass, how to construct the definition, the publish option, and when to use a different 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 the baseline is 3, but the description adds meaningful parameter-level context: publish=true activates immediately, and the definition must be authored against get_schedule_definition_schema. This goes beyond what the schema alone states and helps the agent construct a valid call.

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 operation: adding a new version to an existing schedule by schedule_id. It names the specific resource and explicitly contrasts itself with create_schedule for brand-new schedules, making sibling differentiation immediate.

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 explicitly tells the agent when to use this tool (existing schedule) and when to use the alternative (brand-new schedule → create_schedule). It also provides concrete direction to fetch the definition schema before authoring, which is actionable 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 the sparse annotations, the description discloses important behavioral details: property order is preserved and becomes the editor field order, certain types need x-tessryx-ui hints to render properly, and publish defaults to false. It makes the side effects of the call clear.

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 every sentence carries important operational knowledge. It front-loads the core purpose, then flows naturally from schema authoring details to publishing and versioning alternatives without wasted 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 the output schema exists and all parameters are already described in the input schema, the description covers the remaining contextual needs: version creation, publishing behavior, ordering semantics, and UI rendering caveats. An agent has enough to invoke this tool correctly and avoid common pitfalls.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics for json_schema (order preservation, UI implications, hint requirements) and publish (immediate publication semantics), going beyond the raw schema 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 creates a brand-new schema and implicitly its version 1, using a specific verb and resource. It explicitly distinguishes itself from create_schema_version, so an agent can tell them apart immediately.

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 concrete routing guidance: use create_schema_version when adding a version to an existing schema, use publish_schema for later publishing, and consult get_guide("schemas") for UI hints. This is explicit and directly actionable.

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 openWorldHint=false and destructiveHint=false, providing little behavioral context. The description adds meaningful behavior: versions are immutable, property order is preserved verbatim, media/uploads/cron/colors need an x-tessryx-ui hint or they render as bare text, and publish chooses the live version. It does not fully explain what happens to prior versions or drafts, but it discloses the key operational behaviors 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 a compact paragraph that front-loads the core purpose (add a new version to an EXISTING schema), then gives the key behavioral caveats and the sibling differentiator. Every sentence carries information; no filler or redundancy.

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

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

Given the tool's moderate complexity, 3 parameters, and an output schema, the description covers the essential context: existing schema usage, immutability, property order, publish behavior, and referencing get_guide for hints. It is slightly less complete than the top-tier examples because it doesn't mention version listing or rollback behavior, but it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents schema_id, json_schema, and publish. The description adds value by explaining the verbatim property-order semantics and noting that publish=true is the common create-then-publish convenience. However, the description doesn't add much deep parameter-level detail beyond the schema, keeping it at 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 states a specific verb (add a new version) and resource (an EXISTING schema by schema_id) and contrasts it with create_schema for brand-new schemas. It clearly distinguishes create_schema_version from sibling tools like create_workflow_version and create_schema.

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

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

Explicitly says to use create_schema for a brand-new schema, and this tool for evolving an existing schema. It also explains publish=true as a convenience for create-then-publish in one step, and directs users to get_guide('schemas') for hints. This is strong when-to-use guidance with exclusions.

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 the full behavior: it mints both the workflow and version 1, statically validates the definition before writing, returns created=false on error-severity findings, includes advisory findings on success, and supports publish=true for one-step publication. This goes far beyond the sparse annotations and gives the agent a clear model of side effects and failure modes.

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 well-structured: it opens with the core purpose, then covers definition authoring, validation behavior, publish option, and the sibling alternative. Every sentence carries useful information, and the final parenthetical cleanly prevents confusion with the versioning tool.

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 complex authoring tool, the description covers all essential aspects: how to author the definition, what validation means, what the result indicates on both success and failure, how to publish, and how to handle the versioning alternative. The output schema handles the exact return shape, so no critical information 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?

While the input schema has 100% coverage, the description adds important meaning around the publish parameter (create-and-publish in one step) and the definition parameter (must satisfy a JSON Schema, validated before writing). The mention of slug being URL-safe and optional publication defaulting to draft is also useful. It does not add much for display_name or description, but those are self-explanatory and schema-documented.

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 creates a BRAND-NEW workflow and explicitly distinguishes it from create_workflow_version, which is for adding a version to an existing workflow. The verb 'create' plus the specific resource 'workflow' and the version 1 minting detail leave no ambiguity about what this tool does.

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

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

The description explicitly says to use create_workflow_version when adding a version to an existing workflow, and it tells the agent to use get_workflow_definition_schema before authoring. It also explains that the built-in static validation means a separate validate_workflow pass is unnecessary, which directly informs tool selection.

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

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

Annotations provide only openWorldHint=false and destructiveHint=false, leaving behavioral disclosure to the description. The description delivers the critical behaviors: static validation happens BEFORE the write, error-severity findings mint nothing (valid=false, created=false), and successful writes return advisory findings. This is exactly the kind of side-effect and failure-semantics context an agent needs and is well beyond what the annotations convey.

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

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

The description is dense but every sentence carries a distinct job: scope, authoring source, validation behavior, publish option, and sibling routing. It is slightly heavy with parenthetical asides ('valid=false, created=false'), but the core purpose is front-loaded and nothing is redundant.

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 mutation tool with a nested definition object and a conditional publish side-effect, the description covers the full calling flow: what to pass, how to author it, what validation does, what a failed vs. successful write yields, and how publishing is handled. An output schema exists, so return-value shapes are already documented, and the agent is left with no material 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%, so the baseline is 3. The description adds genuine value on top: it tells the agent to author the definition against get_workflow_definition_schema, explains the validation consequence for a bad definition, and frames publish=true against the alternative publish_workflow tool. This gives each parameter decision context the schema alone doesn't provide.

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

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

The description states a specific verb and resource: 'add a new version to an EXISTING workflow (by workflow_id)'. It explicitly scopes to workflows that already exist and closes with the parenthetical exclusion '(For a brand-new workflow, use create_workflow.)', which clearly differentiates it from its closest sibling without needing to open any schema.

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

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

The description gives explicit when-to-use guidance ('to evolve a workflow you already created'), an explicit when-not-to-use with the named alternative ('For a brand-new workflow, use create_workflow'), and routes to the correct related tools for authoring (get_workflow_definition_schema) and later publishing (publish_workflow). No inference is required.

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

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

Annotations already include destructiveHint: true; the description adds the irreversibility ('Cannot be undone'), cascading version deletion, and the runtime failure behavior of referencing workflows. This is exactly the extra behavioral context that annotations do not provide. No 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?

Two short sentences; the key fact (permanent delete of template and all versions) is front-loaded and every clause adds information. No filler or 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?

For a low-complexity, single-parameter destructive tool, the description covers the object scope, irreversibility, and downstream consequences (runtime failure). The presence of an output schema and annotations handles return and safety details.

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 single template_id parameter is fully documented in the schema (100% coverage), so the description need not repeat it. The description adds no new parameter-level details, so the baseline 3 applies.

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

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

The description uses the specific verb 'permanently delete' with the resource 'api template' and clarifies scope ('all its versions'). It is unmistakably distinct from sibling read, update, publish, and unpublish operations on api templates.

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 conveys clear context: this is an irreversible, destructive removal, and dependent workflow api_calls will fail at runtime. This implies use only when permanent removal is intended, but it does not explicitly name an alternative such as unpublish_api_template or state a direct 'when not to use' condition.

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 goes beyond the destructiveHint annotation by explicitly stating 'This cannot be undone' and clarifying that member resources are untouched, giving full transparency about consequences.

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 two sentences, efficient and well-structured, covering all necessary points without redundancy.

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

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

It fully covers the operation's scope, permanence, and alternatives, making it complete in the context of sibling delete and unpublish tools.

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

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

The only parameter app_id is described in the schema with 'the app id to delete permanently', which matches the description. The tool description adds no further detail, so it stays at baseline.

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 permanently deletes an app and all its versions, and explicitly distinguishes it from unpublish_app, making its 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?

It directly provides guidance on when to use the tool (for permanent deletion) and when not to (use unpublish_app to hide), leaving 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?

Beyond the destructiveHint annotation, the description adds critical behavioral details: deletion is permanent, cannot be undone, unpublishes from CDN first, and leaves referencing content dangling and degraded. This richly discloses consequences the agent needs to know.

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?

Two sentences with no filler. The primary action is front-loaded, followed by essential caveats (permanence, CDN unpublish, dangling references) that each add value.

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

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

For a single-parameter destructive operation with an existing output schema, the description covers all relevant context: what the tool does, side effects, and consequences. Nothing needed for correct invocation 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?

The input schema already fully describes the only parameter (datafile_id) with 100% coverage. The description does not add new parameter-level detail, and the baseline of 3 applies because the schema carries the documentation burden.

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

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

The description states a specific verb ('Permanently delete') and resource ('datafile'), making the purpose unmistakable. It also clarifies the CDN unpublishing step, which distinguishes it from the sibling unpublish_datafile tool.

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 clear context about what happens when the datafile is published, implying this tool is the full deletion path versus merely unpublishing. It does not explicitly name an alternative or exclusion, but the context is sufficient for an agent to decide when to invoke it.

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

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

The description goes beyond the destructiveHint annotation by stating the action is irreversible, that the server purges the public edge URL first, and that the resource no longer appears in list_dynamic_endpoints. This gives the agent crucial behavioral context about side effects and permanence.

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 front-loaded with the core action, followed by a parenthetical behavioral note and a clear differentiation from the sibling. Every sentence adds value with no redundant filler.

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

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

The tool has a single parameter, a destructive semantic clearly disclosed, an output schema, and a clear comparison to the relevant alternative. Nothing an agent needs to correctly select and invoke this tool is missing.

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

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

Schema description coverage is 100% for the single parameter endpoint_id, with the schema already describing it as 'the endpoint id to delete'. The tool description does not add parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Permanently delete' with the resource 'dynamic endpoint', and explicitly contrasts with 'unpublish' by stating this removes the resource entirely. This makes it immediately distinguishable from sibling tools like unpublish_dynamic_endpoint.

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 names the alternative ('Unlike unpublish') and explains the key difference: unpublish does not remove the resource, while this tool does. An agent can confidently decide between delete_dynamic_endpoint and unpublish_dynamic_endpoint based on this 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?

Annotations already mark destructiveHint=true, but the description goes further by disclosing that deletion is permanent, cannot be undone, and cascades to versions and run history. This is meaningful behavioral context beyond the structured hints.

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?

Two sentences carry all essential information with no filler. The primary action and consequence are front-loaded, and the alternative tool is mentioned at the end in one compact sentence.

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

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

For a single-parameter destructive operation with an output schema and clear annotations, the description fully covers irreversibility, scope of deletion, and the key alternative. 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 100%, and the sole parameter schedule_id is already well-described in the schema as 'the schedule id to delete permanently.' The description does not add parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('delete'), a specific resource ('schedule'), and the full scope of the deletion ('all its versions and run history'). It also clearly distinguishes this from unpublish_schedule, so an agent can immediately tell which sibling tool is relevant.

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 when to use this tool and when not to: 'To simply stop it firing without deleting, use unpublish_schedule.' This direct alternative guidance removes ambiguity and is exactly what an agent needs.

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 the destructiveHint annotation, the description discloses irreversible deletion, the removal of all versions, and downstream consequences: bound datafiles/workflows keep dangling references and skip schema validation. This is substantial behavioral context that annotations alone do not provide.

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

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

Two front-loaded sentences carry the essential purpose, irreversibility, and downstream effects with no filler or repetition. Every sentence earns its place.

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

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

For a destructive single-parameter tool with an output schema and strong annotations, the description is complete: it names the target, scope, irreversibility, and effect on bound resources. No critical caller decision is left undocumented.

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

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

Input schema coverage is 100%, so the schema already documents the single schema_id parameter. The description adds that the deletion affects all versions of that schema, but this is a behavioral consequence rather than new parameter-format semantics. Baseline 3 is appropriate.

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

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

The description states a specific action and resource: 'Permanently delete a schema and all its versions.' It clearly distinguishes this delete_schema tool from the many other delete_* siblings by naming the exact target and scope.

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 clearly implies this tool is for permanent removal of a schema, but it does not explicitly state when to choose it over alternatives such as unpublish_schema or how it differs from deleting other resources. Usage must be inferred from the 'permanently delete' wording.

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 annotations already include destructiveHint=true, and the description adds meaningful detail: deletion is permanent, cannot be undone, and downstream endpoints or sub_workflow references will fail cleanly at run/serve time. This gives the agent a concrete understanding of consequences beyond the annotation flag.

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?

Two sentences, no filler, with the most important information front-loaded: permanent deletion and irreversibility. Every sentence adds value and the structure is easy to parse.

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 single-parameter delete tool with destructiveHint and an output schema, the description covers the key operational facts: scope of deletion, irreversibility, and downstream failure behavior. Nothing essential is missing for correct invocation.

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

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

The input schema provides 100% coverage and already describes workflow_id as 'the workflow id to delete'. The description does not add parameter-level nuance, so the baseline score is appropriate.

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

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

The description states a specific verb ('delete'), the resource ('a workflow'), and the full scope ('and all its versions'), which goes beyond the title. It clearly distinguishes this from sibling delete_* tools by naming the exact resource type and its versioned nature.

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 scope is clear: this deletes the workflow and all versions, which helps an agent decide whether it is the right operation. However, it does not explicitly discuss when to prefer this over alternatives or when not to use it, such as when only a single version needs removal.

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 important behavioral context beyond the annotations by stating 'This runs the real outbound request.' This warns the agent that executing the template has live side effects, which is not obvious from destructiveHint=false alone. It also clarifies that this is a live execution, not a preview or simulation.

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 three sentences with no filler: it opens with the core action and output, then gives the use case, then states the critical caveat. 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?

Given the output schema exists, the description only needs to convey purpose, use case, and behavioral caveats—all of which are present. It covers the live request nature, the trace output, and the workflow-debugging context. Nothing essential is missing for an agent to decide when and how to use this 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%, so the schema already documents all four parameters and their meanings. The description mentions 'variables' and 'debug a template' but does not add new parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific action ('Execute an api template live'), the resource ('against the given variables'), and the exact output ('full trace: rendered request... response...'). It clearly identifies this as a debug/execution tool, distinguishing it from the many get/update/publish siblings.

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 when to use it: 'Use this to debug a template before wiring it into a workflow.' It does not explicitly name alternatives or exclusion conditions, but the workflow-context guidance gives clear situational direction.

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 the version selection behavior ('published if any, else latest') and that the definition body is included. This goes beyond the readOnly annotation to explain exactly what the tool returns, enhancing transparency.

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

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

Two concise sentences, front-loaded with the primary purpose, and the alternative tool mention is placed appropriately. No unnecessary verbosity.

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

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

For a simple read tool, the description covers what the tool returns, how to retrieve older versions, and the optional parameter choice. It is complete for an agent to decide when and how to use it.

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 schema already fully describes both parameters (slug and template_id) with 'provide this or template_id' hints. The description adds no additional parameter-specific meaning beyond what is in the schema, so the baseline score of 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?

Clearly states the action (Get) and resource (single api template) and specifies that it returns the current version's definition body. It also distinguishes from reading older versions, making the purpose 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?

Explicitly tells the user when to use this tool vs the alternative: 'Use get_api_template_version to read a specific older version.' This provides clear guidance on when to choose this tool over the sibling 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context by noting the schema is normative ('must satisfy') and that fetching it is a prerequisite step before authoring a definition, which is meaningful 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?

Two tight sentences with no wasted words. The primary purpose is front-loaded, and the second sentence earns its place by connecting the schema to the specific create operations that require it.

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 zero-parameter read-only schema getter, the description covers what the tool returns, which creation tools it supports, and when to call it. The output schema covers return-shape details, so nothing important 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?

The tool takes zero parameters and its input schema documents no properties, so there is nothing to explain. The description adds no conflicting parameter information, and the zero-parameter baseline 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?

The description states a specific verb and resource: fetch the JSON Schema that an api template definition must satisfy. It clearly distinguishes this from sibling definition-schema getters by naming the exact resource type and tying it to create_api_template and create_api_template_version.

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 explicit usage direction: fetch this schema before authoring a definition for the named create tools. It does not list alternatives or exclusions, but the targeted creation tools make the intended workflow unambiguous.

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 states it is a read operation ('Read back', 'Returns') and the annotations (readOnlyHint true, destructiveHint false) align perfectly. No side effects are hidden or misrepresented.

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 two sentences, front-loaded with the main purpose, and includes necessary details without fluff or 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?

The description mentions the return format (JSON string) and the checksum, and explains how the result can be used (diff/patch/resubmit), providing enough context even without an explicit output schema. It is complete for the intended use.

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

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

All three parameters have descriptions in the schema, and the description reinforces the alternative identifiers (slug or template_id) and the optional version behavior. Parameter semantics are fully covered.

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 reads back the full stored definition of an API template version by slug or id, and differentiates from siblings like get_api_template and get_api_template_definition_schema by focusing on the exact definition body and checksum.

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 explicitly explains when to use it: when you need the exact definition body to diff or patch and resubmit as a new version. Also clarifies that omitting version returns the latest, giving precise usage 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 declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: published_manifest is a typed selector, not the raw definition, and it is absent when the app is unpublished. This sets accurate expectations beyond the structured safety hints.

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

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

Three sentences with no filler: the first states the action and resource, the second explains the key return-value behavior, and the third routes to the relevant sibling. Every sentence earns its place.

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

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

For a read-only getter with a full output schema and complete parameter documentation, the description covers all decision points: what is returned, when published_manifest is absent, and which sibling to use for raw definition access. Nothing needed for correct invocation 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 each parameter description already explains the slug-or-app_id relationship. The description repeats this idea in prose but adds no new precedence, format, or combination semantics beyond what the schema already provides.

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 and resource ('Get a single app by slug or id') and explains what is returned: metadata plus published_manifest. It clearly distinguishes itself from get_app_version by contrasting the typed selector with the raw definition body.

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

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

Explicitly tells agents when to use this tool: when they need the metadata and typed published_manifest of the last-published version. It also names the alternative — get_app_version — for raw definition bodies and notes that published_manifest is absent for unpublished apps.

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

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

Annotations already mark the operation read-only and non-destructive, and the description adds return-content context: it returns a JSON Schema (not the app itself) covering selector rules and metadata. This goes beyond the annotations by clarifying what the response describes and that this is a preparatory fetch.

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 well-structured sentence that front-loads the main action ('Get the JSON Schema an app definition must satisfy') and then packs the necessary domain specifics into a clearly separated clause. No filler or repetition of the title is present.

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 zero parameters, a present output schema, and read-only annotations, the description is complete for an agent's decision-making: it states what will be fetched, what the schema covers, and when to call it. There is no missing prerequisite or hidden side-effect that an agent would need to discover separately.

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 tool has zero parameters, so the input schema is already complete (100% coverage). The description has no parameter semantics to add, and the baseline of 4 applies cleanly at this parameter count.

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: 'Get the JSON Schema an app definition must satisfy.' It goes beyond the title by detailing the schema's contents (membership SELECTOR prefix rules, explicit includes/excludes, and display metadata), and it names the downstream tools (create_app / create_app_version), making it unmistakably distinct from sibling definition-schema tools.

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

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

It gives an explicit timing instruction: 'Fetch this before authoring the definition for create_app / create_app_version.' This clearly establishes when the tool is relevant. It does not name alternative definition-schema tools or state exclusions, but the app-specific context is sufficient for an agent to route correctly.

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 the readOnly/destructive annotations, it discloses non-obvious behavior: summarized_kinds omits large kinds, members_complete flips false, count may exceed members length, and the resolved members are always a live lens rather than a pinned list. This is exactly the kind of behavioral nuance an agent must know before trusting the returned member count.

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 every sentence earns its place; it front-loads the core concept and then layers edge cases (summarized kinds, count mismatch) without digression. Slightly verbose relative to a two-line alternative, but the complexity of the behavior justifies the 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?

Given a rich output schema, 100% parameter coverage, and annotations for safety, this description fully covers what the agent needs: return shape, member set semantics, draft-preview behavior, summarized-kind caveats, and what to call instead for full enumeration. Nothing material is missing.

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

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

Schema coverage is 100%, so the schema already documents slug, app_id, and version. The description adds value by clarifying version semantics (published vs latest draft, omit 0 for current), but it doesn't add much beyond the schema's version description. Baseline 3 is appropriate because structured coverage is complete.

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 ('Resolve') and resource ('an app's LIVE member set'), then defines exactly what that set is: the concrete resources its selector currently matches, resolved as union(prefixes) + includes − excludes. This clearly distinguishes it from generic getters like get_app or get_app_version.

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

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

The description explicitly states when to use it ('Use this to see or verify what an app contains'), how version selection behaves ('pass version to preview a draft's members before publishing'), and when NOT to use it for collection items ('see that kind's own list tool with one of the reported slug_prefix values... e.g. list_datafiles'). It names the alternative tool and never claims to page whole collections.

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 destructiveHint=false, and the description adds meaningful behavioral context: it returns a JSON string of the authored definition, includes a checksum, and defaults to the latest version when version is omitted. This goes well beyond the structured 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 the core action, then gives return format, default behavior, and the key sibling distinction. Every sentence earns its place without repetition 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?

For a read-only retrieval tool with an output schema and full parameter documentation, the description is complete: it specifies how to identify the version, what the response contains, the default when version is omitted, and when to prefer the sibling get_app. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value by explaining that slug or app_id can be used interchangeably, and that omitting version fetches the latest version, which clarifies the intended semantics beyond the raw schema.

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

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

The description states a specific verb and resource, 'Read back the full stored definition of an app version by slug or id,' and clarifies the return payload: the authored JSON definition body plus checksum. It also distinguishes this tool from get_app by calling it the 'EDITING view' versus the 'typed published manifest for reading.'

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 tells the agent when to use this tool versus the sibling get_app: use get_app_version for the editing representation to diff/edit/resubmit, and get_app for reading the typed published manifest. It also gives guidance on omitting version to fetch the latest.

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

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

Annotations already mark this as read-only and non-destructive. The description adds useful behavioral context: the asset must be published, and the response includes an absolute CDN URL, content type, and size. 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?

Two tight sentences with no filler. The core action and return values are front-loaded, and the use-case sentence earns its place by guiding invocation.

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

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

For a simple single-asset lookup with a rich output schema and read-only annotations, the description fully covers what the agent needs: what the tool retrieves, the published-asset constraint, and the intended use. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already explains both slug and media_id parameters. The description restates that either slug or media id can be used, but does not add meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states this gets a single published asset by slug or media id and lists what is returned (CDN URL, content type, size). This distinguishes it from sibling list operations like list_assets by emphasizing 'single' and 'published'.

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 a concrete use case: 'confirm an asset exists and fetch the URL to embed.' It provides clear context for when to call the tool, though it does not explicitly name sibling alternatives or 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 and destructiveHint=false, so the safe read nature is established. The description adds the concrete data elements returned, but no additional behavioral traits such as pagination, caching, or permission requirements. It neither contradicts nor substantially extends the annotation coverage.

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?

Two sentences: the first states the operation and its returned fields, and the second provides concrete user intents. Every clause earns its place, and the main purpose is front-loaded.

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 one required parameter, full schema coverage, an output schema, and read-only annotations, the description provides all necessary decision-making information for a simple getter. The use cases also help an agent choose between this and sibling custom-domain tools.

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

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

The sole parameter is fully documented in the schema with 100% coverage, so the description does not need to repeat syntax. The description confirms that the lookup is by hostname, matching the schema exactly. No extra semantic burden falls on the 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 operation: get a single custom domain by hostname. It enumerates the returned content (lifecycle status, DNS records, routing, messages), which distinguishes it from list_custom_domains and other getters. There is no ambiguity about what the tool does.

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 gives practical use cases: answering 'is my domain live yet?' and re-displaying DNS records for a pending domain. It does not explicitly name alternatives or exclusion conditions, but the provided context is strong enough for an agent to select this tool for single-domain lookup.

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 destructiveHint=false, so the safety profile is covered without the description. The description adds useful response-context (includes JSON content and last published CDN path) but does not disclose behavior around identifier conflicts or missing identifiers; this is consistent with the annotations, and the added value is modest.

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?

A single 15-word sentence that front-loads the verb and resource and packs the identification method and key return values into the remainder. There is no filler and no repetition of schema content.

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

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

For a low-complexity read tool, the description plus a 100%-covered schema, safety annotations, and an existing output schema cover nearly everything an agent needs to call it correctly. The only minor gap is edge-case behavior when both slug and datafile_id are provided, which the schema hints at but the description does not settle.

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

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

Schema description coverage is 100%, and the schema descriptions already capture the either/or constraint ('provide this or datafile_id' / 'provide this or slug'). The description's 'by slug or id' reiterates the schema rather than adding new semantics, so the baseline 3 applies because the schema does the heavy lifting.

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

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

The description states a specific verb ('Get'), a specific resource ('single datafile'), and the two identification routes (slug or id). It adds return-content detail ('JSON content and last published CDN path'), and the 'single' qualifier distinguishes it from list_datafiles and the many other get_* siblings targeting different resources.

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

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

The 'by slug or id' phrasing implies the agent should call this when it already holds a datafile identifier and wants the record's full content, but no alternative tool is named and no when-not-to-use condition is given. There is no explicit routing toward list_datafiles for multi-record needs, so usage guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint and destructiveHint, so safety is covered. The description adds meaningful behavioral context by disclosing that the returned definition body is from the current version, choosing 'published if any, else latest' — a non-obvious selection rule an agent needs to know.

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?

Two sentences with no filler. The core purpose and return behavior are front-loaded, and the routing to get_dynamic_endpoint_version is a single useful addition without redundancy.

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

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

For a read-only single-endpoint retrieval tool with two optional parameters, an output schema, and safety annotations, the description is complete. It covers current-version semantics and names the sibling for older versions, so an agent has everything needed to invoke this tool appropriately.

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 both slug and endpoint_id fully described as alternatives. The description briefly restates 'by slug or id' but adds no new semantics, such as precedence if both are provided. The schema carries the parameter documentation, so a 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-resource pair: 'Get a single dynamic endpoint by slug or id', which immediately distinguishes it from listing tools like list_dynamic_endpoints. It further clarifies what is returned (public URL and current-version definition body), and explicitly separates it from get_dynamic_endpoint_version for older versions.

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

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

The description states when to use the tool: reading one dynamic endpoint's current version. It explicitly directs agents to get_dynamic_endpoint_version for specific older versions, providing a clear exclusion. It doesn't mention list_dynamic_endpoints for multi-endpoint retrieval, but 'single' makes that distinction reasonably clear.

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 destructiveHint=false. The description adds context by explaining that the returned schema is a required precondition for authoring dynamic endpoint definitions, which goes beyond the annotations and clarifies the tool's role in the workflow.

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 two sentences with no wasted words. The main purpose is front-loaded, and the second sentence adds essential workflow guidance about which create tools it supports.

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 zero-parameter read-only tool with an output schema, annotations, and clear reference to the dependent create operations, the description is fully sufficient. Nothing needed to invoke the tool correctly is missing.

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

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

The tool has zero parameters, so the baseline is 4 per the rubric. There is nothing additional to document about parameters in the 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 states a specific verb and resource: 'Get the JSON Schema a dynamic endpoint definition must satisfy.' This clearly identifies what the tool does and differentiates it from sibling get_*_definition_schema tools by naming the dynamic endpoint resource explicitly.

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

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

The description gives clear usage context: 'Fetch this before authoring the definition for create_dynamic_endpoint / create_dynamic_endpoint_version.' It does not explicitly mention alternatives for other definition schemas, but the resource-specific naming and sibling list make the applicable context clear.

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 the return payload: the exact authored definition as a JSON string and its checksum. It also explains that omitting version returns the latest, adding behavioral context beyond the readOnlyHint annotation. This is useful for agents planning to diff, patch, or resubmit.

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?

Two sentences with dense, relevant information. The core function is stated first, followed by return format details and the version behavior. No filler or redundant restatement of the title.

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 complete for a read-only tool with an output schema: it states what is returned, how to select the version, and why the return format is useful. It doesn't explicitly warn that exactly one of slug/endpoint_id should be provided, but the schema's descriptions imply that choice.

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

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

Schema description coverage is 100%, so the schema already documents slug, version, and endpoint_id. The description adds that the tool reads 'by slug or id' and repeats the version omitting behavior, but it doesn't meaningfully enrich the parameter semantics beyond what the schema already provides.

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 a specific verb ('Read back'), a specific resource ('dynamic endpoint version'), and the retrieval criteria ('by slug or id'). It distinguishes itself from sibling tools like get_dynamic_endpoint by emphasizing the full stored definition of a version, though it doesn't explicitly name the sibling alternatives.

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 operational guidance ('Omit version to get the latest version') but does not state when to use this tool versus related tools such as get_dynamic_endpoint or preview_dynamic_endpoint. Usage context is implied but not 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description's action 'Fetch' aligns with a read-only operation. The description adds that the output is markdown, which is helpful, and contains no contradictions with the annotations.

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

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

The description is concise and well-structured, with the primary action ('Fetch a Tessryx guide by topic (markdown)') front-loaded. The two additional sentences provide necessary context about list_guides and the intended use case without any superfluous wording.

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 the tool's purpose, output format (markdown), related tool (list_guides), and the appropriate usage context (before authoring). The presence of an output schema means the return value does not need further description, so all necessary information is present.

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

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

The schema description covers 100% of the parameter, explicitly naming 'topic' as the guide topic to fetch, referencing list_guides, and enumerating all allowed enum values. The description adds the 'see list_guides' hint, making the parameter's meaning and accepted values fully clear.

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 fetches a Tessryx guide by topic in markdown format, and it names the sibling list_guides tool for discovering available topics. It also explains when to use this tool (before authoring to avoid trial-and-error), making its purpose unambiguous and differentiated from alternatives.

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 instructs users to use list_guides first to see available topics, and then to reach for the relevant guide before authoring. This provides clear guidance on when to use this tool versus the sibling list_guides tool, and gives a concrete use case scenario.

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

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

Annotations already flag the tool as read-only and non-destructive, and the description adds substantial behavioral context beyond those: transitive traversal, depth limits, version drift visibility, and the unscanned_kinds caveat about empty reverse results. No contradiction 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 description is dense but every sentence adds operational detail; defaults are front-loaded and alternatives are named early. It is slightly longer than strictly necessary, with minor redundancy with the schema's transitivity note, but remains well-organized and scannable.

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

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

Given an output schema exists and all parameters are documented, the description covers the non-obvious runtime behaviors an agent needs: default direction and depth, transitive reverse traversal, version resolution, and the false-empty caveat for schemas. Nothing critical 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%, but the description adds meaning beyond the schema: bare slugs mean @published, custom_domain expects a hostname, depth is only a browsing control, and depended_on_by is transitive. This materially improves the agent's ability to choose correct parameter values.

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: 'Browse how resources connect, in either direction.' It clearly differentiates itself from sibling get_* tools by describing graph traversal semantics and explicitly naming analyze_resource as the alternative for diagnosing breakage.

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

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

Gives explicit when-to-use guidance: use 'depended_on_by' before a delete or breaking edit, and use analyze_resource instead when the question is whether something is broken. This gives an agent concrete decision rules rather than leaving usage to inference.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the description does not need to cover safety. It adds useful behavioral detail beyond annotations: the response includes cron status fields and the current version is selected as published-if-any, else latest. This clarifies version-selection semantics that the schema does not convey.

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

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

Two focused sentences with no filler. The primary capability is front-loaded, and the sibling guidance is placed efficiently at the end.

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 read-only lookup tool with an output schema and fully documented parameters, this description is complete. It explains the resolution behavior for the current version and names the sibling for older versions, so an agent has what it needs to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both slug and schedule_id. The description only restates that lookup is by slug or id and adds no new parameter semantics.

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

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

States a specific verb and resource: get a single schedule by slug or id. It also clarifies what is returned, including cron status and the current version's definition body, and distinguishes itself from get_schedule_version.

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 get_schedule_version instead when reading a specific older version. This gives the agent a clear routing rule and alternative for a closely related sibling 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?

Annotations already declare the operation read-only and non-destructive, and the description adds useful context about the schema's constraints: workflow reference, recurrence as either cron+timezone or interval, and optional static input. This goes beyond the annotations without contradicting 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 two sentences with no filler. The core purpose is front-loaded, followed by a compact parenthetical summarizing the schema's key requirements and a clear directive on when to use the tool.

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 parameterless metadata tool, the description explains what the tool returns, why it matters, and when to call it. The output schema and annotations cover the remaining context, so nothing essential is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific detail because there are none, but it does explain what the returned schema covers, which is the relevant semantic content for this tool.

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 returns the JSON Schema that a schedule definition must satisfy, naming the resource ('schedule definition') and linking it to the specific creation tools. This distinguishes it from sibling definition-schema tools like get_workflow_definition_schema or get_api_template_definition_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?

The description explicitly instructs the agent to fetch this schema before authoring a definition for create_schedule or create_schedule_version, providing a clear when-to-use directive. It does not explicitly mention alternatives or when not to use it, so it stops short of the strongest level of 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?

The description adds meaningful behavioral context beyond the annotations: it discloses that the return value is a JSON string containing the authored body and a checksum, and that omitting version fetches the latest. The readOnlyHint and destructiveHint annotations align with the read-only nature of the description, with no 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 with no filler. The core purpose is front-loaded, and the return-format detail and version default are mentioned efficiently without unnecessary elaboration.

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 complete for this tool's complexity: it covers what the tool returns, how to identify a version, and the default behavior. The output schema and annotations cover return structure and safety, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that slug and schedule_id are alternative lookup keys and that omitting version returns the latest version, reinforcing and extending the schema's parameter descriptions.

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

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

The description states a specific action ('Read back the full stored definition') on a specific resource ('a schedule version') and clarifies the lookup by slug or id. It clearly differentiates this tool from siblings like list_schedule_versions, which lists versions, and get_schedule_definition_schema, which returns the schema rather than the stored definition.

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 clear context for when to use the tool: when you need the exact authored definition body, checksum, or latest version. It does not explicitly exclude alternatives or state when not to use it, but the purpose is specific enough that an agent can infer the correct usage.

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 destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing that only the current version's body is returned and that the response bundles the JSON Schema body with the schema record. 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?

A single front-loaded sentence carries the action, the identification method, the response content, and the purpose with zero filler. Every clause earns its place, and the key scoping detail ('current version') appears before the purpose clause.

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

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

For a simple 2-parameter read-only tool with an output schema, the description covers how to identify the resource, what will be returned, and why the agent would want it. Nothing an agent needs for normal invocation is missing; the precedence if both slug and schema_id are provided is a minor edge not worth penalizing here.

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%, with both slug and schema_id already documented including their either/or intent. The description's 'by slug or id' only restates what the schema says, so it adds no new semantic meaning beyond the structured definitions — 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?

The description states a specific verb and resource — 'Get a single schema' — and adds distinguishing qualifiers: lookup by slug or id, and inclusion of the current version's JSON Schema body. The 'single' qualifier separates it from list_schemas, and 'current version' separates it from version-specific or definition-schema getters among the siblings.

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 clause 'use it to author a datafile that conforms' gives a clear, actionable context for when to invoke this tool, implicitly routing an agent to fetch the schema before creating or updating a datafile. It does not go so far as to name alternatives or state exclusion cases, 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?

The readOnlyHint annotation already covers the read-only nature, but the description adds meaningful specifics: value_preview is a non-sensitive hint (last few characters), and the tool cannot set values through the assistant. These details go beyond the annotation without contradicting it.

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?

Two sentences, front-loaded with purpose, no filler. The first sentence states the operation and constraints; the second provides the alternative path. Every word serves a purpose.

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

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

For a simple metadata-get tool with two optional parameters and a straightforward output, the description covers purpose, key limitations, preview behavior, and the fallback path. It could explicitly reference list_secrets for multi-secret needs, but the singular framing makes that inferable.

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 both slug and secret_id described, including the 'provide this or the other' mutual exclusivity. The description reinforces 'by slug or id' but adds only marginal value beyond the schema's existing parameter documentation.

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 clear verb (get), resource (single secret by slug or id), and scope (metadata only, value never returned). It implicitly distinguishes from the list_secrets sibling by emphasizing 'single' and explicitly clarifies the metadata-only nature.

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 tells the agent when NOT to use this tool — for adding or changing a secret's value — and directs the user to the dashboard URL instead. It also states the value is never returned, setting expectations for when this tool cannot fulfill a value request.

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 read-only and non-destructive behavior. The description adds useful behavioral context about what is returned (current version, definition body, version numbers), going beyond the basic annotation coverage.

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?

Two concise sentences efficiently convey the tool's purpose, scope, and alternative, with no redundant or fluff content.

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

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

The description provides sufficient context for a get operation, including what is returned and when to use an alternative. It is complete for an agent to decide when and how to invoke the tool.

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

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

The input schema already describes each parameter and their exclusivity. The description adds no additional parameter meaning, so it meets but does not exceed the baseline.

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 (get) and resource (workflow), and specifies it retrieves the current version with definition body and version numbers. It also distinguishes itself from get_workflow_version, making its purpose 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?

Explicitly instructs to use get_workflow_version for specific older versions, providing clear guidance on when not to use this tool and when to use the alternative.

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

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

The readOnlyHint annotation is consistent with the implied read-only behavior, and the description adds clarity about the purpose without conflicting 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?

Two sentences are efficient and directly convey the tool's purpose and usage, with no redundant 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?

The description is complete for a simple getter: it states what is retrieved, the target resource, and the related create tools, covering 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?

The tool has no parameters, and the empty input schema fully covers this. The description adds no conflicting parameter information.

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 retrieves the JSON Schema for workflow definitions, and explicitly distinguishes it from other definition schema getters by referencing workflow-specific create tools (create_workflow / create_workflow_version).

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 explicit when-to-use guidance: fetch this before authoring a workflow definition for the create tools, leaving no ambiguity about appropriate invocation.

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 destructiveHint=false, and the description adds substantial behavioral context beyond that: output is decoded as a string, the output_truncated flag is explained, and the storage retention policy is disclosed with conditions (live endpoint serve runs keep only the first few KB; run_workflow/preview runs store in full). This surfaces a real gotcha the agent needs to interpret results correctly. 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?

All three sentences earn their place: the first front-loads purpose and return payload, the second discloses the truncation caveat with the remediation, and the third states the storage rule for user-triggered runs. No redundant or filler content; appropriately sized for a single-parameter tool with one meaningful behavioral caveat.

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 read-only, single-parameter tool with 100% schema coverage, an output schema present, and safety annotations in place, the description covers everything an agent needs to call it correctly: what is returned, how the output is decoded, what the truncation flag means, and when the stored output may be incomplete. No meaningful gap remains.

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% — run_id is already documented as 'the run id returned by run_workflow,' so the schema carries the full burden. The tool description only restates 'by run id' and does not add format, provenance, or validation details beyond the schema. Baseline 3 is appropriate given the high coverage.

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

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

The description states a specific verb ('Get'), a precise resource ('the stored record of a past workflow run'), the key by which it is retrieved (run id), and the exact fields returned (status, content_type, output, output_truncated). This clearly differentiates it from siblings like get_workflow_run_traces (traces vs. record) and list_runs (single record vs. list), even without naming them.

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 when to use the tool (retrieving a stored past run record) and explicitly routes around a limitation: for runs from a LIVE ENDPOINT SERVE, the stored output is truncated, and the 're-run or preview the endpoint' alternative is named to see a whole render. It does not, however, explicitly position this tool against its closest retrieval siblings (get_workflow_run_traces, list_runs), which keeps it just shy 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 declare readOnlyHint=true and destructiveHint=false, and nothing contradicts them. Beyond that, the description discloses significant non-obvious behavior: pagination, shortening of large captured values with a marker, scope entries that point at adjacent block outputs instead of repeating values, and that UNATTENDED runs replace literal expressions with their path and are shortened harder overall. These are exactly the surprises an agent needs before invoking the tool.

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

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

The description is front-loaded with the core purpose in the first sentence, then flows logically through trace structure, shortening behavior, and unattended-run caveats. It is long, but each clause carries distinct information — nothing is filler. It is slightly dense with parenthetical examples, but the complexity of the behavior justifies the 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?

Given an output schema exists and safety annotations are present, the description covers all remaining needs: the content of each step trace, paging behavior, the shortening edge cases, the unattended-run difference, and the concrete workaround for full capture. Nothing an agent needs to correctly invoke or interpret the tool is left unexplained.

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%: run_id, page_size, and page_token each have meaningful schema descriptions, including the next_page_token contract for paging. The description only reinforces this ('by run id', 'paged') without adding format or syntax detail, so the baseline 3 applies since the schema carries the burden.

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 first sentence states a specific verb and resource: 'Get the full per-step execution trace of a run by run id (paged)'. This clearly distinguishes it from sibling read tools like get_workflow_run (run-level metadata) and list_runs (run listing), and the rest of the text specifies exactly what a trace contains: blocks, inputs, outputs, error_message, and variable scope.

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

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

Explicit when-to-use guidance is given: 'Use this to debug why an expression or block produced the wrong value.' It also provides when-not guidance and names concrete alternatives: for literal values on unattended runs use get_workflow_version, and to capture full values re-run via run_workflow / preview_dynamic_endpoint / run_schedule_now. The routing is unambiguous.

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 destructiveHint=false. The description adds meaningful behavior: it returns the definition body as a JSON string plus content_sha256, and describes the latest-version fallback. This goes beyond the structured annotations without contradicting them.

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