Tessryx

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it enumerates what counts as error vs warning vs info, states deployable is true only with no errors, notes incomplete_nodes for run-time-built references, and warns that severities for non-root subjects are not weighted by reachability. No contradiction with readOnlyHint — the hypothetical modes explicitly change nothing.

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

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

Front-loaded and dense with useful content, but the middle sentence is a single run-on enumeration of parenthetical examples that is hard to scan. The severity taxonomy would be far more usable as a short list; some examples (domain routing elsewhere, @latest following) earn their place, others pad the 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?

Covers subject scope, the hypothetical modes, the findings shape, severity semantics, the deployable flag, incomplete_nodes, and the reachability caveat for non-root subjects. Combined with an output schema, an agent has everything needed to call this correctly and interpret results.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by framing hypothetical='delete'/'unpublish' as a no-op preview and 'publish' as a draft-resolution check, and by calling out app as the usual kind. It adds context but does not restate the slug/version syntax, which the schema already handles.

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

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

States a specific verb+resource+question ('check whether a resource and everything it depends on is sound — the deployability question') and explains the subject kinds, including that an APP is the usual one and that roots are walked to the end of each chain. This is clearly distinguishable from siblings like validate_workflow or get_resource_graph, which are read/get or narrower validation 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?

Explicit routing: 'Pass hypothetical to preview a change instead', 'run it before deleting something other resources may use', and hypothetical='publish' checks the draft you are about to publish. It also names the condition under which non-root subjects are analyzed, so the agent knows when this tool applies versus a plain get.

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 carry readOnly=false, destructive=false, idempotent=false, openWorld=true, so the safety profile is covered. The description adds real value beyond that: the call creates a template plus its first version, and by default that version is an unpublished draft unless publish=true. It doesn't mention what happens to the created template if definition validation fails, or whether the slug must be unique — a small residual gap.

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

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

Front-loaded with the distinguishing fact (brand-new template + version 1) and free of filler. Minor redundancy: the instruction to fetch the definition JSON Schema with get_api_template_definition_schema repeats what the 'definition' schema description already says.

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 create-with-nested-definition tool with an output schema (so return values need no explanation), the description covers the whole path: obtain schema, author, test with execute_api_template, publish in-line, or defer to the version tool. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and every parameter is documented in-schema, so this is the baseline case. The description restates publish's create-then-publish meaning and points at the JSON Schema requirement for 'definition', but adds no format or constraint detail beyond the schema.

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

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

States a specific verb and resource ('create a BRAND-NEW api template') plus the side effect that defines it ('mints the template + its version 1'). The parenthetical explicitly differentiates it from create_api_template_version, so an agent can route between the two without opening either schema.

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

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

Gives an ordered workflow: fetch the definition JSON Schema via get_api_template_definition_schema, author against it, iterate with execute_api_template, then optionally pass publish=true. It also names the exclusion case (adding a version to an existing template → create_api_template_version), which is exactly the alternative an agent could confuse this with.

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

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

Annotations already establish non-read-only, non-idempotent, non-destructive, open-world behavior. The description adds meaningful context: publish=true publishes immediately, omission leaves a draft, and the owning service validates the definition 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?

The description is compact and front-loaded: it states the operation, scope, schema dependency, publish option, and alternative within a few dense sentences. No sentence 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?

With an output schema present and annotations covering safety traits, the description supplies everything an agent needs: existing-template scope, required schema lookup, publish behavior, and the sibling to use for new templates.

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

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

Schema description coverage is 100%, and the schema already explains template_id, definition, and publish in detail. The description reinforces the publish behavior and schema-authoring flow but does not add parameter syntax or semantics beyond what the schema 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?

States a specific verb and resource: add a new version to an EXISTING api template by template_id. It clearly scopes the operation to existing templates and distinguishes itself from create_api_template for brand-new 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?

Explicitly says to use this tool for evolving an existing api template and directs the agent to create_api_template for a brand-new one. It also explains the publish=true option and the default draft behavior.

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 the generic mutation profile (readOnly=false, destructive=false, non-idempotent, open-world); the description adds the consequential behavior: it mints both an app and version 1, membership is captured automatically by the prefix rule rather than hand-added, an empty definition is legal but publishing requires a non-empty membership, and publish=true publishes immediately.

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

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

Front-loaded with the create action and the sibling exclusion, and nearly every clause carries information. It is dense with parentheticals and nested examples, which slightly taxes scanning, but nothing is filler.

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

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

For a nested-object, non-idempotent creation tool with 5 params, the description covers the authoring loop, the validation source (get_app_definition_schema), the publish precondition, and the sibling alternative. Return values are covered by the output schema, so nothing material is missing.

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

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

Schema coverage is 100% so the baseline is 3; the description climbs above it by explaining that slug is the folder prefix that drives membership capture and that publish=true is the common create-then-publish path. Those are consequences of the parameters, not just restatements of their types.

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 ('create a BRAND-NEW app') and immediately scopes it ('mints the app + its version 1'). It explicitly names the sibling it is not (create_app_version) so an agent can route without inspecting schemas.

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

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

Gives an explicit entry point ('Start here when building a page or an API bundle'), names the prerequisite workflow (get_app_definition_schema, then author under the prefix), and names the alternative tool for adding a version to an existing app. It also flags when the result is publishable vs. a valid empty draft.

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 readOnly=false, destructive=false, openWorld=true, idempotent=false. The description adds value beyond them: it clarifies that publish=true makes the version the live manifest immediately while omitting it leaves an unpublished draft, and that the service validates the definition on submit. It stops short of saying whether an unpublish/rollback path exists once a version goes live.

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 the core operation, then the schema-source instruction, then the publish switch, then the sibling exclusion. No filler; every clause carries routing or behavioral information.

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

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

For a mutation against a nested free-form object, the description supplies the missing pieces: where the JSON Schema lives, that it is validated on submit, what publish does, and which sibling handles brand-new apps. Return values are covered by the existing output schema, so nothing material 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it ties publish to its live-manifest consequence and tells the caller where to obtain the definition contract (get_app_definition_schema, or copy via get_*_version). That is more than a restatement of the schema text.

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

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

States a specific verb and resource ('add a new version to an EXISTING app (by app_id)') and scopes it to changing the membership selector or display. It also explicitly disambiguates from the sibling create_app, so an agent can route without opening either schema.

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

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

Gives the condition for use (modifying an existing app's selector/display), names the alternative for the opposite case ('For a brand-new app, use create_app'), and routes to get_app_definition_schema for authoring. The publish=true vs. draft default fork is spelled out as a decision the caller makes.

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

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

Annotations only say readOnlyHint=false, idempotentHint=false, openWorldHint=true; the description adds the crucial behavioral facts an agent cannot infer: the claim grants nothing until ownership is proven, the response contains exactly two DNS records (ownership TXT plus permanent routing CNAME) in dns_records, and a human must act before the flow advances.

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 tightly packed sentences, front-loaded with the core action, then the critical caveat ('grants NOTHING until ownership is proven'), then the next-step routing. No filler and every sentence carries a distinct operational instruction.

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

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

Covers the full call lifecycle for a non-idempotent, human-in-the-loop mutation: what is created, what comes back, who must act, and which follow-up tool to call. With an output schema present, return-value detail is already handled, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds prioritization the schema does not: slug_prefix and root_endpoint are optional 'here' and are usually deferred to update_custom_domain after verification, which steers the agent to send only hostname initially.

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

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

States a specific verb+resource ('claim a custom hostname for this tenant') plus the side effect (generating a DNS challenge), and explicitly distinguishes itself from the sibling verify_custom_domain and update_custom_domain. An agent can tell exactly what this tool does and does not accomplish without opening the schema.

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

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

Gives an explicit ordered workflow: present the returned DNS records to the human, wait for them to be added, then call verify_custom_domain. It also names the alternative path for slug_prefix/root_endpoint ('usually set later with update_custom_domain'), so the agent knows which params to defer and which sibling to use.

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 mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description only needs to add context. It adds genuinely non-obvious behavior: schema validation is mandatory, property order in json is preserved verbatim, and creation does not itself publish to the CDN.

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

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

Three short sentences, front-loaded with purpose and prerequisite, with no filler. Each sentence adds useful operational context rather than restating 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 tool has an output schema, so return values need not be explained. The description covers the key workflow around schema binding, verbatim property ordering, and the separate publish step; it could say more about slug uniqueness or validation failure behavior, but it is nearly complete for a create 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 baseline is 3. The description reinforces that schema_id is mandatory and must be authored or selected first, but most parameter meaning is already carried by the schema itself.

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 gives a specific verb and resource ("Create a new datafile") and narrows the scope to one holding a JSON object. It is clearly distinguishable from create_schema, update_datafile, and publish_datafile, which are named or implied as separate concerns.

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 states the prerequisite (a datafile MUST be bound to schema_id and schema tools should be used first) and gives the downstream step (publish_datafile to serve from CDN). It does not explicitly say when to use update_datafile instead of create_datafile, but the create-vs-publish routing is 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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the call mints a version 1 alongside the endpoint, the definition binds a workflow by versioned-slug reference plus a cache setting, and publish=true immediately takes the endpoint live. It does not mention that a newly created endpoint is public/open-world at the tenant subdomain or what happens to the slug after creation, which keeps it below a 5.

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 identity and the two key routing facts (publish shortcut, sibling for new versions) are front-loaded, with the exclusionary parenthetical last. Sentences are dense but every clause carries information; it is a little long-winded around the definition/workflow binding.

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 with a nested definition object and an output schema, the description covers what is created, how the definition is authored, and the publish path. Return-value details are legitimately left to the output schema, and the remaining gap (post-creation slug mutability, visibility of the live endpoint) is minor.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already carries the heavy slug, publish and content_type semantics. The description adds meaning beyond the schema only for publish (one-step go-live) and definition (must satisfy the fetched JSON Schema and reference a workflow version plus cache setting), which is useful but modest given how much detail the schema already supplies.

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 ('create a BRAND-NEW dynamic endpoint') and clarifies that it mints both the endpoint and its version 1. It explicitly distinguishes itself from the closest sibling, create_dynamic_endpoint_version, so an agent can pick correctly without opening a schema.

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

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

Gives explicit when-to-use branches: pass publish=true for one-step go-live, or publish later with publish_dynamic_endpoint, and use create_dynamic_endpoint_version instead when the endpoint already exists. It also points to get_dynamic_endpoint_definition_schema as the prerequisite for 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 already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true); the description adds genuinely useful context beyond them: the version is added to an existing endpoint rather than creating one, publish defaults to draft, and the owning service validates the definition on submit. It stops short of describing failure/rollback behavior or what the created version record contains, which keeps it from a 5.

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 tight paragraph with the core action and the existing-vs-new distinction front-loaded, followed by the schema-authoring pointer and the publish shortcut. Every clause carries information, though the parenthetical alternative could be folded more compactly.

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, annotations covering safety, and full schema coverage, the description supplies exactly what's missing: which sibling to use instead, how to obtain the definition schema, and the publish shortcut. Nothing an agent needs to invoke this correctly is absent.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including publish defaulting to false and the definition object's validation. The description's 'Pass publish=true to take this dynamic endpoint version live immediately' largely restates the publish parameter's schema text, so the baseline 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?

States a specific verb and resource ('add a new version to an EXISTING dynamic endpoint') and scopes it to an endpoint_id, immediately separating it from the brand-new-endpoint sibling create_dynamic_endpoint. An agent can distinguish it from the version-creation siblings (create_app_version, create_schema_version, etc.) by the resource named.

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

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

Explicitly names when to use it ('evolve a dynamic endpoint you already created'), when not to ('For a brand-new dynamic endpoint, use create_dynamic_endpoint'), and points at the prerequisite tool get_dynamic_endpoint_definition_schema for authoring the definition. The publish=true shortcut is also called out as an alternative to a separate publish step.

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=false, idempotentHint=false, and openWorldHint=true. The description adds meaningful behavioral context beyond those annotations: it mints both the schedule and version 1, publish=true starts firing, omitted publish leaves a draft, and the owning service validates the definition on submit. It does not address duplicate-slug conflicts or permission requirements, but the key side effects and lifecycle behavior are 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 front-loaded with the core action and is dense but purposeful. The final parenthetical alternative is useful, though the single long sentence makes it slightly less scannable than it could be.

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 nested definition, versioning model, and publish semantics, the description is complete enough for an agent to call the tool correctly. It points to get_schedule_definition_schema for the nested JSON Schema, and an output schema exists so return values do not need to be described.

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 five top-level parameters. The description still adds substantial meaning for the nested definition object by explaining the workflow reference, cron-plus-timezone versus interval recurrence, and optional static input bound as $input on every fire.

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: create a brand-new schedule and mint its version 1. It explicitly distinguishes this from create_schedule_version and publish_schedule, so the agent can select the correct sibling without opening schemas.

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 routing: use this tool for a new schedule, use create_schedule_version when adding a version to an existing schedule, and use publish_schedule when not publishing inline. It also explains the publish=true one-step activation versus leaving the version as a draft.

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 non-read-only, non-destructive, non-idempotent profile; the description adds real value by explaining that publish defaults to a draft and that the owning service validates the definition on submit. It does not warn that repeated calls create additional versions (relevant given idempotentHint=false), which is the main behavioral gap.

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

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

A single tight paragraph with the existing-vs-new distinction front-loaded and the actionable guidance (schema tool, publish flag, alternative tool) in descending order of importance. The parenthetical aside is the only mildly interruptive element.

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

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

With an output schema present, the description needn't explain returns, and it covers prerequisites, validation, draft-vs-publish, and the sibling alternative. What remains unstated is version lineage (whether the new version inherits the prior definition) and the consequence of calling it repeatedly.

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 publish, definition, and schedule_id thoroughly. The description only restates the publish=true behavior and the definition-authoring route, adding little beyond the structured fields; 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 gives a specific verb and resource ('add a new version to an EXISTING schedule') and explicitly scopes the operation by schedule_id. It also names the sibling it is not (create_schedule for brand-new schedules), so an agent can separate it from create_schedule and the publish_* family.

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 prerequisite (an existing schedule_id) and routes brand-new schedules to create_schedule, and it points at get_schedule_definition_schema for authoring. It stops short of saying how this differs from using publish_schedule or create_schedule_version-style flows when only activation is desired, so it is clear but not exhaustive.

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

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

Annotations declare readOnly=false, idempotent=false, destructive=false, but the description adds real substance beyond them: the call mints a schema plus version 1, property order is preserved verbatim and drives editor field order, and omitting publish leaves an unpublished draft. It stops short of covering failure modes such as slug collisions or permission requirements, which matters for a non-idempotent creation 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 core identity ('create a BRAND-NEW schema') is front-loaded and every clause carries information, but the description is a single dense block of em-dash-separated fragments that is harder to scan than it could be. Nothing is redundant, though the parenthetical about create_schema_version could stand alone more cleanly.

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

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

With an output schema present, return values need no explanation, and the description covers the creation semantics, publish flow, and json_schema authoring constraints for a 5-parameter tool with nested objects. Missing: behavior on duplicate slug or validation failure of the supplied json_schema, which an agent creating a resource would want to know.

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, but the description goes beyond the schema for json_schema by explaining the consequence of property order (it sets editor field order) and that media/entity/cron/color fields need x-tessryx-ui hints. The publish parameter's effect on version resolution is also clarified. Minor gap: 'hierarchical' slug syntax is left to the schema.

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

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

States a specific verb (create) and resource (schema) with a precise scope: 'BRAND-NEW schema (mints the schema + its version 1)'. It also explicitly distinguishes itself from create_schema_version and publish_schema, so an agent can route correctly without opening a schema.

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

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

Names the alternative directly ('To add a version to a schema that already exists, use create_schema_version') and explains the two publish paths: publish=true now versus publish_schema later. It also routes to get_guide("schemas") when x-tessryx-ui hints are needed, which is a genuine when-to-use pointer.

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=false, destructiveHint=false and idempotentHint=false, so the description only needs to add context — which it does substantially: property order is preserved verbatim and drives editor field order, versions are immutable, an x-tessryx-ui hint is required for media/entity-reference/cron/color fields, and publish controls which version is live. These are non-obvious behavioral consequences an agent could not infer from the schema.

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 key scoping distinction is front-loaded in the first sentence, and every sentence carries information. It is dense — the x-tessryx-ui sentence is a parenthetical detour — but nothing is padding, and the closing exclusion is well placed.

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 annotations, a full schema description, and an output schema, the description covers the mutation's semantics, ordering side effect, highlighting prerequisite, and publish behavior. It omits what happens on invalid json_schema or a nonexistent schema_id, which is the main remaining gap for a write operation.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real meaning on top — that publish=true is the one-step create-then-publish path and determines which version is live, and why property order in json_schema matters. It stops short of describing failure or validation behavior for a malformed json_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?

States a specific verb and resource ('add a new version to an EXISTING schema') and immediately scopes it to existing schemas by schema_id. It explicitly names the sibling it is not ('For a brand-new schema, use create_schema'), so an agent can distinguish it from create_schema and publish_schema without opening a schema.

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

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

Gives explicit when-to-use (evolve an existing schema), when-not (brand-new schema → create_schema), and names the alternative for publishing (publish_schema, or publish=true inline). It also routes to get_guide("schemas") for the x-tessryx-ui requirement, which is a concrete prerequisite 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?

Goes well beyond the annotations: it discloses that the definition is statically validated before write, that error-severity findings abort creation with valid=false, created=false and returned findings, and that advisory findings are surfaced on success. Annotations only cover the safety profile (non-readonly, non-destructive, non-idempotent), so this adds real behavioral value an agent could not infer.

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

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

Front-loads the core identity and the new-vs-version distinction, then layers validation semantics and the publish shortcut. Dense but every sentence carries operational meaning; the parenthetical advisory examples add minor bulk but aid authoring.

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 nested-object mutation tool with an output schema, it covers what an agent needs: schema-fetch workflow (get_workflow_definition_schema), validation timing, failure result fields, and return shape {content_type, output}. Little is left to guess.

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 earns above baseline by explaining the consequence of the definition parameter (pre-write validation, failure semantics) and reinforcing the publish=true one-step behavior. It doesn't add much on slug/display_name/description beyond the schema, but the definition semantics are genuinely informative.

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 ('create a BRAND-NEW workflow'), clarifies that it mints the workflow plus version 1, and describes what a workflow composes. It explicitly distinguishes itself from create_workflow_version in the closing sentence, so an agent can route without opening either schema.

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

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

Explicitly names the alternative for the adjacent case ('To add a version to a workflow that already exists, use create_workflow_version') and tells the agent a separate validate_workflow pass is unnecessary because validation runs inline. It also documents the publish=true shortcut for create-then-publish.

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

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

Annotations only cover safety/read-write hints; the description adds substantial behavior: static validation before write, error findings produce valid=false/created=false, successful writes surface advisory findings, and the publish flag's effect. This is exactly the kind of transactional detail annotations cannot express.

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

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

Front-loads the core action and constraint, then layers validation behavior and alternatives. Dense but every sentence carries routing or behavior information; only the trailing parenthetical is mildly redundant with the opening scope.

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 nested-object mutation with an output schema present, the description covers the prerequisite schema fetch, validation outcomes, failure modes, and publishing path. 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%, so baseline is 3; the description adds real value by explaining the definition must satisfy get_workflow_definition_schema, the pre-write validation contract, and the create-then-publish semantics of publish. It stops short of enumerating each parameter but compensates meaningfully above the schema.

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

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

States a specific verb+resource ('add a new version to an EXISTING workflow') and explicitly scopes it against the sibling create_workflow ('For a brand-new workflow, use create_workflow'). An agent can distinguish it from create_workflow and publish_workflow without opening any schema.

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

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

Gives explicit when-to-use (evolve an existing workflow), when-not (brand-new workflow → create_workflow), and the in-step alternative for publishing (publish=true vs later publish_workflow). All routing decisions are named.

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 flag destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description still earns credit for two things the annotations do not say: that all versions are removed along with the template, and that a referencing workflow api_call fails cleanly at run time. It stops short of disclosing permission requirements or whether the template must be unpublished first, which would be needed for a 5.

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, front-loaded with the action and its scope, then the irreversibility and the downstream consequence. No filler, no restatement of the title, and every clause carries new information.

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

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

With annotations covering the safety profile and an output schema covering the response, the description only needs to explain scope and consequences, which it does well (all versions, irreversible, breaks referencing api_calls). The one real gap is preconditions/permissions for a destructive, non-idempotent operation, which keeps it off a 5.

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?

There is a single required string parameter with 100% schema description coverage, so the schema already tells the agent everything ("the api template id to delete"). The description adds no format, sourcing hint (e.g., get it from list_api_templates), or constraint beyond what the schema provides, 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 opens with a specific verb and resource ("Permanently delete an api template") and adds the cascading scope ("and all its versions"), which tells an agent exactly what this removes. Against siblings like delete_app or delete_workflow, the resource noun is unambiguous, and against unpublish_api_template the word 'Permanently' does the differentiating work.

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?

Usage is only implied: the agent can infer 'call this when you want the template gone for good' from 'Permanently delete' and 'Cannot be undone'. There is no explicit when-to-use, no named alternative (e.g., unpublish_api_template or update_api_template to retire without destroying), and no precondition such as the template needing to be unpublished first.

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

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

Annotations already declare destructiveHint=true, but the description adds the non-obvious behavior that deletion is irreversible and, crucially, scoped: member resources are untouched and persist independently. That scope disclosure goes well beyond what the annotations or schema 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?

Three short sentences, front-loaded with the irreversible delete and its scope, then the alternative. Every sentence earns its place with no redundancy.

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

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

Output schema exists and annotations carry the safety/idempotency profile, so the description needn't explain returns. Combined with the scope and alternative guidance, nothing needed to call this correctly is missing.

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

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

Only one parameter and schema coverage is 100%, so the schema fully documents app_id. The description adds no syntax or format detail beyond 'the app id to delete permanently', so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete an app and all its versions') and immediately distinguishes it from the sibling unpublish_app. An agent can tell exactly what this does 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?

Explicitly names the alternative ('To simply hide the app without deleting, use unpublish_app'), giving the condition that routes an agent to the correct tool. When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already flag destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known; the description adds real substance on top by disclosing the side effect of CDN unpublishing and the irreversible dangling-reference consequence. It stops short of saying what a second call does or whether missing IDs error, which matters given idempotentHint=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?

Two tight sentences: the verb and its CDN side effect come first, the irreversible consequence second. No filler, no 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?

Return values are covered by the output schema and the destructive semantics plus cascade behavior are spelled out, which is what an agent most needs for a delete. Minor gap: nothing on error behavior for a nonexistent ID or on repeat calls, notable given the non-idempotent annotation.

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?

Single required parameter with 100% schema description coverage, so the schema fully documents datafile_id. The description adds no format, sourcing, or lookup guidance beyond that, which is the expected baseline when the schema does the work.

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

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

Specific verb+resource ("Permanently delete a datafile") with the key qualifier that CDN unpublishing is folded in. It implicitly distinguishes itself from the unpublish_datafile sibling via the parenthetical, but never names that sibling outright, so an agent must infer the boundary.

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

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

The description implies when this is appropriate (permanent removal, not just unpublishing from the CDN), but it never explicitly says "to merely take offline use unpublish_datafile" or states prerequisites such as required permissions or whether the datafile must be unpublished first. Usage context 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 flag destructiveHint=true and idempotentHint=false, so the description could have coasted; instead it adds irreversibility ('Cannot be undone') and, importantly, the non-obvious fact that edge caches keep serving the public URL until s_maxage_seconds expires. That cache-staleness caveat is a genuine behavioral disclosure unavailable from any structured field.

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

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

Three short sentences, zero waste, and the irreversible/cache caveats are front-loaded right after the core action. Each sentence carries distinct information that an agent needs before calling 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?

The tool has an output schema and fully annotated safety profile, and the description covers everything left: permanence, list visibility, non-recoverability, and cache propagation lag. Nothing an agent needs in order 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?

One parameter with 100% schema description coverage, so the schema already documents endpoint_id ('the endpoint id to delete'). The description adds nothing parameter-specific, which is acceptable but deserves only baseline credit.

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 ('Permanently delete a dynamic endpoint') and immediately contrasts it with the nearest alternative operation, unpublish. An agent can distinguish it from unpublish_dynamic_endpoint and delete_dynamic_endpoint's other siblings without opening a schema.

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

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

Explicitly names the alternative operation ('Unlike unpublish, this removes the resource entirely') and gives the observable consequence ('no longer appears in list_dynamic_endpoints'), which effectively communicates when to pick this over unpublish. It stops short of stating a positive selection criterion such as 'use only when you are sure the endpoint will never be needed', so not 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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds material value beyond that by disclosing what is destroyed (versions and run history) and that the action is irreversible. It does not mention required permissions, a minor omission.

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

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

Three short sentences, front-loaded with the destructive verb and cascade scope, then irreversibility, then the alternative. No filler sentences.

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 mutation with an output schema, the agent needs cascade scope, irreversibility, and an escape hatch to a safer sibling – all present. 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% and the single parameter is documented in-schema as 'the schedule id to delete permanently.' The description adds no syntax or format detail beyond the schema, 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?

Specific verb 'permanently delete' plus resource 'schedule' and explicit cascade scope ('all its versions and run history'). It also names the sibling it is not (unpublish_schedule), so the agent can distinguish it without opening a schema.

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

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

Explicitly routes the agent to the alternative when the goal is only to stop firing: 'use unpublish_schedule.' That is a clear when-to-use/when-to-use-instead statement rather than implied 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?

The annotations already declare destructiveHint=true and idempotentHint=false, but the description adds material context beyond them: the deletion is irreversible, it spans all versions, and existing datafiles/workflows retain dangling references and silently skip validation. That downstream side effect is exactly the kind of consequence an agent cannot get from the annotations.

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

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

Two sentences, zero filler, and the irreversibility warning is front-loaded right after the action statement. The dangling-reference caveat earns its place because it is non-obvious behavior.

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?

Output schema exists, so return values need no explanation, and the annotations plus description together cover safety, scope, and side effects. The only gap is whether deletion fails or proceeds when resources are bound, which the description only partially answers with 'keep the dangling reference'.

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 schema_id parameter is fully documented in the schema itself (100% coverage), and the description adds nothing about its format or where to obtain it. Baseline 3 applies because the schema already carries the 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?

Specific verb (permanently delete) plus the resource (schema) and the exact scope (all its versions). This is clearly separable from siblings like update_schema, unpublish_schema, and delete_datafile without opening any schema.

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

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

The description makes the destructive intent obvious, so the implied usage is real deletion rather than unpublishing. But it never names an alternative (unpublish_schema vs delete_schema, or update_schema for changes), so the agent must infer the when/when-not conditions.

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 destructiveHint=true, so the safety profile is covered; the description earns credit for going beyond it by disclosing the cascade to all versions and the downstream consequence that endpoints and sub_workflow references fail at run/serve time. It stops short of stating auth/permission requirements or the non-idempotent behavior the annotations declare.

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, zero filler. The irreversible nature is front-loaded immediately after the action statement, and the downstream-impact detail follows it in dependency order.

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

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

With an output schema present, return values needn't be explained, and the description covers irreversibility and runtime consequences well. The one notable omission for a destructive lifecycle tool is whether the workflow must be unpublished first or what the caller should do about existing endpoint references beforehand.

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

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

Only one parameter at 100% schema description coverage, so the schema fully documents workflow_id. The description adds no format, sourcing, or lookup guidance (e.g. where to obtain the id via list_workflows), leaving this 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?

A specific verb and resource ('Permanently delete a workflow') plus the important scope detail that all versions go with it. It doesn't explicitly differentiate itself from adjacent lifecycle operations like publish_workflow or the version-level siblings, but the resource and blast radius are unambiguous.

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

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

The 'Cannot be undone' clause signals caution and implies a last-resort action, but the description never states when to use this versus alternatives (e.g. leaving a workflow unpublished or deleting only a version) or what prerequisites must hold. Usage is inferable 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 destructiveHint=true, openWorldHint=true, and non-idempotent, and the description reinforces this by warning 'This runs the real outbound request' and describing the full trace returned. It does not cover failure modes, auth requirements, or rate limits, so it adds meaningful but not exhaustive context.

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: purpose and return value first, debugging guidance second, the live-request warning last. 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?

Output schema exists, so the description need not detail return values, and it still summarizes them usefully; annotations cover the safety profile. Minor gaps remain around error behavior or side effects on the target system, but nothing essential 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 description coverage is 100% and each of the four parameters (slug, template_id, version, variables) is documented in the schema, including the slug-or-id alternative and version defaulting. The description only alludes to 'given variables' and adds nothing beyond the schema, so baseline 3 applies.

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

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

States a specific verb ('execute') and resource ('an api template') plus the scope of what is returned (rendered request and response). It is clearly distinguishable from siblings like get_api_template, create_api_template_version, or validate_workflow.

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

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

Gives an explicit use case: 'Use this to debug a template before wiring it into a workflow.' It does not name a concrete alternative (e.g., preview_dynamic_endpoint or get_api_template) or state when not to use it, which keeps it below 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, idempotentHint, and non-destructive. The description adds genuinely useful behavior beyond them: the version-resolution rule (published if any, else latest) and the fact that the definition body is included. It doesn't cover error behavior for a missing slug/id, keeping it below a 5.

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, zero waste, with the scoping/return rule front-loaded ahead of the sibling redirect. Every clause 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 lookup with an output schema, the description covers what an agent needs: what is fetched, how the version is chosen, and where to go for other versions. Return-value detail is correctly left to 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% and both parameters already document the 'provide this or slug' either/or constraint. The prose restates 'by slug or id' without adding format or precedence guidance, so the schema carries the load — baseline 3.

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

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

States a specific verb and resource ('Get a single api template') and specifies the lookup keys (slug or id). It also defines what is returned ('the definition body of its current version'), which cleanly distinguishes it from get_api_template_version and list_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?

Explicitly names the alternative tool and the condition that selects it: 'Use get_api_template_version to read a specific older version.' An agent can route between the two 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 annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered for this zero-argument read. The description adds the sequencing constraint but nothing about what the returned schema looks like or when it might change; with an output schema present, that omission is minor, so a 3 is fair.

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. The 'what' comes first and the 'when' second, which is the right front-loading for a prerequisite fetch 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?

With an output schema present, return values need no explanation, and the zero-parameter input eliminates ambiguity. What remains unclear is whether the same schema applies to update_api_template, a small but real gap for a tool whose entire job is to be consulted before authoring.

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 no parameters and the input schema is an empty closed object, so there is nothing to disambiguate. Baseline 4 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?

Specific verb plus resource: it returns the JSON Schema that an API template definition must satisfy. That makes it immediately distinguishable from get_api_template / list_api_templates, and the named consumers (create_api_template / create_api_template_version) anchor its role in the family of 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?

The description gives explicit ordering guidance: 'Fetch this before authoring the definition for create_api_template / create_api_template_version.' That is a clear call condition. It omits update_api_template, which also needs a definition, so the set of consumers is not complete.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that: the return payload is the exact authored body as a JSON string plus a checksum, and it explains how the body is meant to be reused. Return-shape detail is somewhat redundant with the output schema, keeping it at 4.

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, front-loaded with the core action, followed by return detail and the version default. Every clause earns its place with no repetition or filler.

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

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

With an output schema present and full param coverage, the description supplies enough: what is returned (definition body + checksum) and the version default. Only the sibling differentiation against get_api_template is left implicit.

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 would be 3, but the description reinforces the slug/id duality and the version-omission semantics ('Omit version to get the latest version'), matching the schema's '0 for latest' note. It adds minor interpretive value over the schema rather than fully new syntax.

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 ('Read back') and resource ('full stored definition of an api template version'), and scopes it by slug or id. This is distinguishable from get_api_template (metadata-level) by the 'version definition' framing, though it never explicitly names that sibling as the alternative.

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 clear usage context — omit version for latest, and the definition-as-JSON-string is intended for diffing or patching and resubmitting as a new version, which implicitly routes the agent to create_api_template_version next. No explicit when-not or named alternative, so not 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: what published_manifest contains, and that it is missing for unpublished apps. It stops short of describing error behavior or pagination, but for a single-item read there is little else to disclose.

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 the core action and immediately followed by return-value semantics and the sibling routing. The clause 'so you can read the app's shape from concrete fields' is mildly redundant with the preceding TYPED selector explanation, but nothing else 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?

An output schema exists, so the description is not obliged to enumerate return fields, and it correctly focuses on the one nuance an agent cannot infer: published_manifest's absence for unpublished apps. The minor gap is that neither schema nor description states what happens if zero arguments are passed, which is relevant given required parameters is 0.

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

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

Schema description coverage is 100% and both parameters already document the 'provide this or the other' relationship. The description's 'by slug or id' restates the schema rather than adding syntax, format, or precedence rules for when both are supplied — the baseline 3 applies.

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

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

States a specific verb and resource ('Get a single app by slug or id') and goes further to name what is returned: metadata plus published_manifest, defined as the typed selector of the last-published version. It also explicitly distinguishes itself from get_app_version, so an agent can pick between the two without opening either schema.

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

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

Names the alternative tool and the exact condition that selects it: 'to read/edit the raw definition body (draft or any version) use get_app_version.' It also flags the edge case that published_manifest is absent for unpublished apps, so the agent knows when the result will be incomplete.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing the shape of the returned schema (selector semantics, prefix rules, display metadata), letting the agent anticipate what it will get before calling.

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 the primary noun phrase, and the sequencing instruction comes last where it belongs. The parenthetical elaborating the selector is dense but every clause carries meaning.

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

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

An output schema exists, so return values needn't be spelled out, yet the description still characterizes the key payload component (the membership selector). For a zero-param read-only schema fetch, nothing an agent needs 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, so there are no semantics to explain and the baseline of 4 applies. The description correctly spends no words on inputs and instead details the output contract.

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 the JSON Schema an app definition must satisfy) and then enumerates the schema's contents: membership SELECTOR with prefix rules, slug folder, member kinds, explicit includes/excludes, and display metadata. This clearly separates it from data-returning siblings like get_app, get_app_version, and get_app_members.

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?

"Fetch this before authoring the definition for create_app / create_app_version" gives explicit ordering and names the exact consumer tools, which is exactly the guidance an agent needs. It lacks a negative case (e.g., when not to call it), but with a zero-param read-only tool an exclusion is close to unnecessary.

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

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

Annotations already cover the read-only, idempotent safety profile, but the description adds substantial behavior beyond that: members are a live lens rather than a pinned list, the published version resolves by default, summarized kinds are omitted from members and reported under summarized_kinds with members_complete=false, and count can exceed members length. These are exactly the surprises an agent needs to know about.

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

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

The definition leads with the core claim (live resolved set) and then layers the important caveats about summarized kinds. It is dense but largely load-bearing; a few clauses (the parenthetical about blog datafiles, the repeated draft-preview phrasing also present in the schema) could be trimmed.

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 fan-out resolution tool, the description covers the semantics, default version resolution, the truncation/summarization contract, the count-vs-length discrepancy, and the escape hatch to sibling list tools. An output schema exists, so the description does not need to explain return shapes, and it still sketches the member record shape usefully.

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 restates the version parameter's default-resolution semantics that the schema already documents ('omit (0) for the current one ... preview a draft's members before publishing'), and adds no detail about slug versus app_id beyond the schema.

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

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

States a specific verb and resource ('Resolve an app's LIVE member set') and immediately clarifies that this is not the stored rules but the resolved union of the selector's matches. This clearly distinguishes it from get_app/get_app_version (which return the rule definitions) and from list_datafiles (which lists a single kind).

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

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

Explicitly states when to use it ('see or verify what an app contains'), when to use a sibling instead ('To see the items of a summarized kind, call that kind's own list tool ... e.g. list_datafiles'), and warns what it will not do ('never pages a whole collection'). It also explains that passing version previews a draft's members before publishing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds real value beyond that — the body comes back as a JSON string plus a checksum, and the string is meant to be parsed and resubmitted — but it says nothing about size limits, error behavior for a nonexistent version, or whether historical versions are immutable.

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 the action, then the return shape, then the sibling disambiguation. Every clause carries information an agent needs; nothing is repeated from the annotations.

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

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

With an output schema present, return values need not be explained, and the rich annotations cover safety and idempotency. The description fills the remaining gaps that structure cannot: the JSON-string encoding of the body, the checksum, the default-version behavior, and the read-vs-edit split against get_app.

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 slug/app_id/version are already documented, and the description only restates the "omit version for latest" default. It earns slightly above baseline by framing why you would fetch a specific version at all — to diff or edit and resubmit — which the schema does not convey.

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

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

States a specific verb and resource ("Read back the full stored definition of an app version by slug or id") and immediately names what it is not: "This is the EDITING view; get_app returns the typed published manifest for reading." An agent can distinguish this from get_app and list_app_versions without opening any schema.

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

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

Gives the explicit selection rule against the nearest sibling — use this for editing, get_app for reading the typed published manifest — and states the default behavior ("Omit version to get the latest version"). The intended downstream workflow (diff, edit, resubmit as a new version) is spelled out rather than implied.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: only *published* assets are returned, and the response will contain URL, content type and size.

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, zero filler, front-loaded with the purpose and then the use case. Nothing in it could be removed without losing 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?

Both optional identifiers are documented in the schema, an output schema covers the return shape, and annotations cover safety semantics. The description's extra job — telling the agent it only sees published assets — is done.

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 already documents the 'provide this or the other' rule, so the schema does the heavy lifting. The description adds mild value by restating that lookup can be by slug or media id, but no format examples or clarification of precedence is given.

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 published asset') plus the two lookup keys and what is returned (CDN URL, content type, size). The word 'single' and 'published' clearly separate it from list_assets and the rest of the get_* family.

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 when to reach for it: 'Use this to confirm an asset exists and fetch the URL to embed.' It gives a positive use case but does not name an alternative (e.g. list_assets for discovery) or state 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by specifying what information is returned, including lifecycle status, DNS records, routing details, and human-facing check/certificate messages.

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 tightly written sentences, front-loaded with the operation and followed by concrete use cases. Every sentence earns its place and there is no redundant or vague text.

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-resource lookup with one fully documented parameter, rich annotations, and an output schema, the description is complete. It explains the returned information and practical usage without needing to duplicate schema 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 hostname parameter is fully documented in the schema with an example ('shop.customer.com'), and schema description coverage is 100%. The description reinforces that lookup is by hostname but does not add syntax or formatting details beyond what the schema already 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 states a specific verb and resource ('Get a single custom domain by hostname') and scopes it to a single lookup rather than a list. It also enumerates the returned facets (lifecycle status, DNS records, routing, messages), making it clearly distinct from sibling tools like list_custom_domains, create_custom_domain, and verify_custom_domain.

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 clear usage context: answer 'is my domain live yet?' and re-display DNS records for a pending domain. However, it does not explicitly name alternatives or exclusions, such as when to use list_custom_domains or verify_custom_domain instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description adds one useful behavioral detail — that the response includes JSON content and the last published CDN path — but says nothing about failure modes (missing slug, unpublished datafile) or permissions.

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

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

A single front-loaded sentence with zero filler; the identifying verb and resource come first and the payload detail follows.

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

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

An output schema exists for the return shape and annotations cover safety, so the description's job is small and it mostly does it. Missing only the edge-case behavior (what happens when neither parameter is supplied or the datafile is not found).

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 both parameters are documented there with their mutual-exclusivity note ('provide this or slug'). The description only echoes 'by slug or id' without adding format or precedence rules, so baseline 3 applies.

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

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

States a specific verb (get), resource (datafile), scope (single) and lookup key (slug or id), which implicitly contrasts with list_datafiles. It does not explicitly name the sibling alternatives the way a top-tier definition would.

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?

Usage is only implied: 'single' vs the list_datafiles sibling, and 'by slug or id' hints at the lookup pattern. There is no explicit when-to-use/when-not, no note that exactly one of the two optional parameters should be supplied, and no alternative named.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value beyond that by disclosing the version-resolution rule ('published if any, else latest') and what the payload contains. It stays silent on auth requirements or error behavior when neither identifier is supplied.

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 the primary capability and followed by a single disambiguation pointer. Nothing is padded or repeated from the annotations.

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

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

An output schema exists, so return structure need not be spelled out, yet the description still signals the useful payload contents. For a trivial two-param read tool this is nearly complete; only the neither-identifier-supplied case is left unstated.

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

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

Schema description coverage is 100% and both parameters are already documented as alternatives ('provide this or endpoint_id'). The description restates the slug-or-id choice but adds no format examples or precedence rule for when both are passed, so 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?

Names a specific verb and resource ('Get a single dynamic endpoint by slug or id') and enumerates what comes back: the public URL and the definition body of the current version. It also distinguishes itself from the near-identical sibling get_dynamic_endpoint_version, so an agent can choose without opening both schemas.

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

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

Explicitly routes the agent to get_dynamic_endpoint_version 'to read a specific older version', which is the main ambiguity for this tool. It does not mention other adjacent siblings like get_dynamic_endpoint_definition_schema or list_dynamic_endpoints, so it is clear context but not exhaustive when/when-not 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 declare readOnly, idempotent and non-destructive, so the safety profile is free. The description adds genuinely new behavioral context: this is a prerequisite read that must precede authoring a definition, establishing workflow ordering. Return shape is covered by the output schema, so no further disclosure is owed.

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 what it returns and followed by the ordering instruction. Every clause earns its place, with no restatement of the name or annotations.

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

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

With no parameters, an output schema present, and annotations covering safety, the only things an agent needs are purpose and sequencing — both supplied. Nothing required 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?

The tool has zero parameters, which is the baseline-4 case; there are no arguments whose meaning could be clarified. The description correctly implies no inputs are needed.

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 the JSON Schema a dynamic endpoint definition must satisfy') and names the exact siblings it feeds ('create_dynamic_endpoint / create_dynamic_endpoint_version'), so an agent can separate it from the many other get_*_definition_schema and get_dynamic_endpoint 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?

Explicitly says when to call it ('Fetch this before authoring the definition for create_dynamic_endpoint / create_dynamic_endpoint_version'), which is a concrete pre-condition ordering. It does not state exclusions (e.g. that it should not be called when updating an existing endpoint), but for a zero-arg lookup that gap is small.

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 readOnly/idempotent/non-destructive, and the description still adds real substance: the definition comes back as a JSON string body plus a checksum, and omitting version defaults to latest. It stops short of covering error behavior for an unknown slug or version, which would complete the picture.

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: what it returns, what the payload is useful for, and the version default. Front-loaded with the core action and free of filler.

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

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

With an output schema present, the description needn't explain return structure, and it correctly focuses on the JSON-string body and checksum. Coverage is nearly complete for a read tool; only failure modes for invalid slug/version are unaddressed.

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 all three parameters are documented in the schema, including the 'omit (0) for latest' semantics. The description only restates the slug/id alternative and the version default, adding no format or edge-case detail beyond the schema.

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

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

The description uses a specific verb+resource pair ('Read back the full stored definition of a dynamic endpoint version') and scopes it by slug or id. It implicitly distinguishes itself from get_dynamic_endpoint (metadata) by emphasizing 'full stored definition', but it never names the sibling, so an agent must infer the boundary.

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

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

It gives a clear use context ('so you can parse it to diff or patch and resubmit as a new version') and states that omitting version gets the latest. It does not say when to prefer this over get_dynamic_endpoint, get_dynamic_endpoint_definition_schema, or list_dynamic_endpoint_runs, leaving the sibling routing 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered without the description. The description adds only that the payload is markdown and that guides are prep material — useful but thin, with no statement on size, paging, or caching.

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 with zero filler: what it does and returns first, then how to pick a topic and when to reach for it. Nothing restates 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?

An output schema exists, so return-value explanation is unnecessary, and the single enum parameter is fully specified in the schema. Combined with the discovery pointer to list_guides, an agent has everything needed to call this correctly on the first try.

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 sole parameter is a 14-value enum documented inline, so the schema carries the full burden. The description's only addition is pointing at list_guides as the way to discover valid topics; it adds no per-topic meaning beyond the enum.

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

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

Specific verb (fetch) plus specific resource (a Tessryx guide by topic) and even the return format (markdown). It is clearly distinguishable from every sibling, all of which operate on platform resources rather than documentation.

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

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

Explicitly routes discovery to list_guides and states the trigger condition for calling it: consult the relevant guide before authoring to avoid trial-and-error. Both the alternative and the when-to-use condition are stated outright.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: depended_on_by is transitive and not depth-limited while depends_on follows depth hops, edges carry authored vs. resolved version text so drift is visible, and unscanned_kinds means an empty reverse result does NOT imply no dependents. That last caveat is exactly the kind of non-obvious behavioral context the description should carry.

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

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

The purpose is front-loaded and every sentence carries information (direction semantics, version drift, unscanned_kinds caveat, alternative tool). It is dense and long-ish for a graph tool, but there is no filler; a slightly tighter phrasing of the edge-metadata sentence would earn a 5.

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

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

An output schema exists, so return-format explanation is unnecessary, and the description still covers the two things an agent most needs that structure cannot convey: the asymmetry between the two directions and the unscanned_kinds false-empty trap. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description meaningfully extends the parameters: it explains what each direction semantically returns, frames depth as a browsing control versus analyze_resource following chains to the end, and notes version-suffix resolution for the resource slug. It stops short of restating kinds, but the value added over the schema is real.

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 action (browse how resources connect) and a specific resource (resource graph), and explicitly distinguishes two traversal directions. It also names the sibling it is not (analyze_resource), so an agent can separate this from the other get_* tools 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?

It gives explicit when-to-use guidance: call depended_on_by before a delete or a breaking edit, and use analyze_resource instead when the question is whether something is broken rather than what it connects to. Both the positive case and the alternative are stated.

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

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

The description adds meaningful behavior beyond the annotations: it discloses the returned cron status fields and the version-selection rule ('published if any, else latest'). Annotations already cover the read-only, idempotent, non-destructive profile, so remaining gaps such as permission requirements or not-found behavior are minor.

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 used with zero waste: the core behavior and returns are front-loaded, followed by the sibling alternative. Every clause carries actionable information.

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

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

With an output schema present and annotations covering safety traits, the description supplies the remaining decision-relevant context: what is returned, how the current version is selected, and where to go for older versions. Nothing needed 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?

The schema has 100% description coverage for both parameters, and the description reinforces that either slug or id may identify the schedule. It does not add syntax, format, or precedence details beyond what the schema already documents, so the baseline 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?

The description states a specific verb and resource ('Get a single schedule'), explains the lookup keys (slug or id), and enumerates the returned data (cron status and current version definition body). It clearly distinguishes itself from get_schedule_version by naming that sibling 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?

It explicitly routes the agent to get_schedule_version when a specific older version is needed, which is a clear alternative-selection rule. It does not state when not to use this tool or mention list_schedules as a discovery path, but the context is otherwise 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds value by characterizing what the returned schema enforces: a workflow reference, two mutually exclusive recurrence forms, and optional static input. It stops short of describing response shape, but an output schema exists, so that omission is acceptable.

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

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

One dense sentence, front-loaded with the action and resource, followed by a parenthetical that carries the important schema-shape details, then the usage rule. No filler and nothing redundant with the annotations.

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

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

With an output schema present, return values need not be explained. The description covers what the tool returns conceptually, when to call it, and what it feeds into, which is everything an agent needs for a zero-parameter discovery 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a parameterless tool is 4; no misinformation is present.

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 gives a specific verb and resource ('Get the JSON Schema a schedule definition must satisfy') and immediately disambiguates the content and domain (workflow reference, recurrence, static input). An agent can distinguish this from the many sibling '*_definition_schema' tools without opening any schema.

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

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

It states an explicit ordering rule ('Fetch this before authoring the definition') and names the exact consumers ('create_schedule / create_schedule_version'). This is both a when-to-use instruction and a routing hint to the correct follow-up tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the definition is returned as a JSON string requiring parsing, and a checksum accompanies it, which matters for diff/patch/resubmit workflows.

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, no filler: purpose first, then return shape, then the version-omission rule. Every sentence carries information an agent would otherwise have to infer.

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?

Output schema exists, but the description still clarifies the JSON-string return and checksum, which is the key detail for downstream diff/patch use. For a read-only lookup with full schema coverage, nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and already documents slug vs schedule_id and 'omit (0) for the latest version'. The description restates the slug-or-id choice and the omit-version behavior without adding format or edge-case detail beyond the schema, so the baseline 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?

States a specific verb and resource: reads back the full stored definition of a schedule version, keyed by slug or id. This clearly separates it from get_schedule (current schedule state) and list_schedule_versions (enumeration), which appear as 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?

Explicitly says to omit version for the latest, and frames the use case: parse the body to diff or patch and resubmit as a new version. It stops short of naming exclusion conditions against get_schedule/get_schedule_definition_schema, but the context for choosing this tool is 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 readOnly, idempotent, and non-destructive, so safety is covered. The description adds a detail not in the structured fields: the body returned is that of the *current* version, which matters for an agent authoring a conforming datafile and hints that historical versions live elsewhere.

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 sentence that front-loads the resource and lookup keys, then closes with the motivating use case. No filler, nothing redundant with the schema.

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

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

For a two-parameter read-only tool with full schema coverage, an output schema, and rich annotations, this is close to sufficient. A minor gap remains around error behavior when the slug is unknown or when both identifiers are passed.

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 itself states the 'provide this or schema_id' either/or rule for both parameters. The description's 'by slug or id' merely restates rather than adding format or precedence guidance (e.g., which wins if both are supplied), so baseline 3 applies.

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

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

States a specific verb and resource ('Get a single schema'), the lookup keys ('by slug or id'), and the payload ('JSON Schema body of its current version'). The word 'single' plus the authoring intent cleanly separates it from list_schemas and the list_* 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?

'use it to author a datafile that conforms' gives a concrete when-to-use tied to a downstream task (create_datafile/patch_datafile). It does not name alternatives such as list_schemas or get_schema_version, so the routing is implied rather than explicit.

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

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

Adds essential behavior beyond the readOnly/non-destructive annotations: the value is never returned, value_preview is only a non-sensitive hint such as trailing characters, and secret values cannot be set through this assistant. These are exactly the constraints an agent needs to avoid misusing 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?

Two sentences, front-loaded with the core lookup behavior, followed by the critical limitation and the redirect to the dashboard. There is no wasted text.

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

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

Complete for a metadata-only getter: the input schema covers both lookup parameters, annotations cover safety, and an output schema exists. The description fills the critical gap by explaining that secret values are never returned and cannot be modified 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 coverage is 100%, and the schema already documents that slug or secret_id must be provided as alternatives. The description reinforces lookup by slug or id but does not add format details or selection guidance beyond the schema, so 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?

States a specific verb and resource: get a single secret by slug or id, with the scope explicitly limited to metadata. This clearly distinguishes it from the sibling list_secrets and from mutation tools that would change a secret.

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 this tool cannot set or change a secret's value and directs the user to the web dashboard for that. The usage context is clear, though it does not explicitly name list_secrets as the alternative for browsing multiple secrets.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real semantic context beyond that: which version body is returned and what version numbers accompany it. It stops short of describing failure behavior (e.g., neither slug nor id supplied) or the shape of the returned definition.

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 core capability front-loaded and the alternative-tool pointer last. Every clause carries 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?

An output schema exists so return values need not be spelled out, and annotations cover safety; the description fills the important gap about version resolution. Minor omission: behavior when both identifiers are given, or when neither is.

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 both parameters already document the 'provide this or the other' relationship. The description's 'by slug or id' only restates that, adding no syntax, format, or precedence guidance for the zero-required-parameter case.

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 workflow by slug or id') and precisely scopes what comes back: the current version's definition body plus latest/last-published version numbers. It cleanly distinguishes itself from get_workflow_version and from list_workflows.

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

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

Explicitly routes the agent: 'Use get_workflow_version to read a specific older version.' It also encodes the version-resolution rule (published if any, else latest), which is exactly the decision an agent needs before calling either 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 readOnly, idempotent, non-destructive and closed-world, so safety is fully covered. The description's only extra signal is the sequencing requirement — valuable but thin, with no mention of response size or whether the schema is stable across versions.

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, no waste, and the call-ordering instruction is front-loaded where the agent will read it. Every clause 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?

A zero-parameter read-only lookup with an output schema and full annotation coverage needs only to state its purpose and its place in the authoring flow, both of which are present. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The input schema is an empty closed object, consistent with 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?

Specific verb and resource: 'Get the JSON Schema a workflow definition must satisfy'. It clearly separates itself from get_workflow / get_workflow_version because it returns a schema rather than the workflow object, and it names the downstream tools it exists to serve.

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

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

Explicit prerequisite ordering: 'Fetch this before authoring the definition for create_workflow / create_workflow_version.' An agent knows exactly when to call it and which sibling calls it feeds.

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