DenkOps

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

Annotations only declare the write/non-idempotent profile, so the description adds real value: the token is returned exactly once and cannot be retrieved again, it is scoped and revocable, and it requires workspace-owner authorization. It omits failure behavior and any rate or count limits on tokens.

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 action and audience, then the critical one-time-return caveat, then the permission constraint. No filler or restated 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?

For a 5-parameter creation tool with no output schema, the description covers purpose, the irreversible one-shot secret return, and authorization. It leaves the scope defaults (env_scope none, all projects, 90-day expiry) entirely to the schema, which is acceptable but leaves the agent slightly under-briefed on scope implications.

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 80%, so the schema already documents projects, env_scope, agent_type, and expiry defaults. The description only gestures at scoping ('scoped') without explaining label, project restriction, or expiry choices, so it adds little beyond the schema. 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 ('Mint a new scoped, revocable DenkOps connection token') plus the concrete use cases (CLI, CI job, agent, GitHub Actions deploys). It does not explicitly distinguish itself from siblings like regenerate_connection or update_connection_scopes, though the word 'new' implies the distinction.

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 when-to-use context (automating a CLI, CI job, or agent) and a concrete example (GitHub Actions deploys), plus a hard prerequisite ('Workspace owners only'). It stops short of naming alternatives or stating when not to use this tool versus regenerate_connection.

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 past the annotations: it discloses the 500-file / 5 MB limits, that .env files are actively rejected, that a missing denkops.json creates a new project, and the naming fallback order (name, package.json, pyproject.toml). It also states the return value (live URL), which the annotations cannot convey since there is no output 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?

Front-loads the action and outcome in the first sentence, then the branching rule (project_id), then the hazard (.env), then the hard limits. Dense but every clause carries information and nothing is repeated from 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 write operation with no output schema and nested file objects, the description covers action, input shape, failure conditions, limits and the return value. An agent could invoke it correctly from this text alone.

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?

Adds real meaning beyond the 67%-covered schema: it explains how `name` interacts with denkops.json, when `project_id` applies, and that `files` must include every source file rather than a delta. Only minor gap is it does not mention the `encoding` enum, which the schema covers on its own.

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

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

Opens with a specific verb and resource ("Deploy a project to DenkOps by sending its files") plus the outcome ("get the live URL back"). It is clearly distinct from siblings like redeploy, rollback, start_project and list_deployments, since it is the only tool that takes a file payload.

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 routing logic: omit project_id to create a new project, pass project_id to ship a new version of an existing one, and .env files are rejected so env vars should be set separately. The gap is that it never names the `redeploy` sibling or explains when re-uploading files beats redeploying an existing build.

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 a non-read-only, non-destructive, open-world, non-idempotent operation, and the description adds genuinely useful context beyond them: no charge occurs until the user confirms on Stripe, and permission gating behavior for non-owners. It does not mention link expiry or whether repeated calls mint distinct sessions, which is the main remaining behavioral unknown 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 sentences with no filler: the action and its three modes come first, then the no-charge guarantee and the permission rule. Every clause carries decision-relevant 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 one-optional-parameter tool with no output schema, the definition covers the action, the modes, the safety guarantee, and authorization behavior. It is only slightly short of complete because it does not say what form the returned link takes or how long it stays valid.

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 already documented, so the baseline is 3. The description earns an extra point by tying extra_slots to specific modes ('subscribe (optionally with extra slots), add slots to an existing subscription'), clarifying that the same parameter serves both a new and an existing subscription context.

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

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

The description gives a concrete verb and resource ('Get a one-click Stripe link for this workspace') and enumerates the three outcomes it can produce: subscribe with optional extra slots, add slots to an existing subscription, or repair a failed payment. That clearly separates it from the read-only sibling get_plan, though it never names that sibling, so it stops short of a top score.

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 when-to-use cases are explicit (new subscription, slot expansion, failed payment recovery) and the eligible audience is stated ('Workspace owners only; other members are told which owner to ask'). What is missing is a when-not-to-use note pointing at get_plan for simply inspecting the current plan or quota.

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 openWorldHint=false, so the safety profile is fully covered. The description adds what the branding consists of and where it is applied, which is helpful context, but says nothing about behavior when branding is unset (defaults), whether the icon is returned as a URL or binary, or auth requirements.

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?

It is a single front-loaded sentence with no filler or redundancy. There is no structural elaboration (no notes or caveats), but nothing in the 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?

For a one-parameter, read-only lookup with rich annotations and no output schema, the description conveys enough to call it correctly. The only mild gap is what happens when a project has no custom branding configured.

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

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

Schema description coverage is 100% with a single required project_id parameter whose pattern and meaning are documented in the schema. The description adds no further meaning about the identifier, 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 pairs a specific verb ("Show") with a specific resource (a connector project's brand colours and icon) and even names where that branding surfaces (hosted sign-in and consent pages). An agent can distinguish it from set_connector_branding by the read/retrieve framing, though it never names that sibling explicitly.

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

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

Usage is only implied: it is evidently a read of branding metadata for a given project. There is no statement of when to prefer this over alternatives (e.g., set_connector_branding for mutation) and no prerequisites or exclusions, so the agent must infer intent.

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 openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing further about behavior — it does not say whether the response is static reference text, a structured outline, or version-specific to the user's project, nor whether any auth or workspace context is required. Some added context, but thin against a lowered bar.

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 with the primary scope ('structure, configure, deploy') front-loaded and the supported stack details following as qualifiers. Every clause carries information; there is no padding or repetition 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?

With zero parameters, a rich annotation set and no output schema, the description needs only to establish scope and it does so completely enough for selection. The one residual gap is that it never says what comes back (reference documentation content) or that it is the canonical starting point before build/deploy actions, which would help an agent order its calls.

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 the baseline is 4 and the description correctly avoids inventing any. The scope words in the description (bun-Hono vs python-FastAPI, defineMcp) act as implicit topic filters an agent can reason about, though it does not confirm whether the full guide is always returned or can be targeted.

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 ('Explains how to') and enumerates the covered subject matter: project structure, denkops.json configuration, and deployment for bun-Hono or python-FastAPI APIs and defineMcp-based MCP servers. This makes clear it is a documentation/guidance tool, distinct from action siblings such as deploy or start_project. It stops short of explicitly contrasting itself with those siblings, which keeps it out of 5 territory.

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: an agent can infer this is the thing to read before structuring or deploying a DenkOps project, but there is no explicit 'use this when' clause and no mention of when not to use it or which sibling to prefer instead. No prerequisites or sequencing guidance (e.g., consult before calling deploy) is stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the fixed 24-hour lookback window and the specific data families returned, which matters since there is no output 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?

One sentence, front-loaded with the verb and resource, with the enumerated contents and time window packed in without filler. Every clause contributes 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 one-parameter read tool with full annotation coverage, the description is nearly complete: it names the time window and the returned data, compensating for the absent output schema. The only minor gap is that units or aggregation semantics for latency percentiles are not specified.

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 parameter (project_id) is fully documented in the schema with a pattern constraint, so the schema carries the load. The description only implies that the id names a DenkOps project and adds no syntax, format, or scope details beyond that.

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 ('Get') and resource ('a DenkOps project's request metrics') and enumerates the payload: latency percentiles, error rate, latest resource sample, rejected-request count. It is clear enough to distinguish from list-style siblings, though it does not explicitly contrast with near neighbours like get_status or get_trace.

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 metrics content and the 'last 24h' window suggest this is the tool for checking project performance and health. There is no statement about when to prefer it over get_status, get_trace, or get_workspace_overview, and no prerequisites or exclusions are given.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is settled. The description adds what the call actually surfaces (slot counts, subscription status, renewal date, prices), which is real context beyond the annotations, though it says nothing about access requirements for reading billing data.

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 first defines the payload, the second defines the trigger. Front-loaded and free of restated title text 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 no output schema, the description usefully lists what comes back, and a read-only, zero-parameter tool of this kind needs little more. Minor gaps remain around whether admin-level access is required and how the price data is formatted.

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, so there is nothing for the description to disambiguate and the baseline of 4 applies. The schema is trivially complete and the description correctly spends no words on inputs.

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 ('Show') and resource ('the workspace's plan') and enumerates the returned content: slots used and free, subscription status, renewal date, and prices. That content profile makes it distinguishable from siblings such as get_billing_link and get_workspace_overview 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 two concrete triggers: when a new project might not fit, or when the user asks about their plan or slots. It does not name an alternative tool or state when not to use it, so it stops short of full routing guidance.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds that the result is the span set for one trace, which is useful context, but says nothing about ordering, truncation, or volume of spans returned.

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: verb, resource, and both identifying inputs in one pass. Nothing is redundant or buried.

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

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

With no output schema, the description carries the burden of describing the return value, and it only says 'spans' without indicating shape, ordering, or size. For a two-parameter read tool with strong annotations this is minimally adequate, but an agent still lacks a picture of what comes back.

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 both parameters are already documented in the schema with patterns and required status. The description only restates that both ids are used to identify the trace, adding no meaning beyond what the schema provides — the appropriate baseline of 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?

The description uses a specific verb ('Get') plus a precise resource ('the spans of a single DenkOps request trace'), so an agent knows it returns span data rather than a trace summary or list. It doesn't explicitly name sibling list_traces as the alternative for enumerating traces, so differentiation is implied by 'single' rather than stated.

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 implied by the 'by project_id and trace_id' phrasing: this tool is for retrieving one already-known trace. There is no explicit when-to-use/when-not clause, no pointer to list_traces for discovering a trace_id, and no statement about what happens if the trace doesn't exist.

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 the safety profile is covered. The description adds real value beyond those annotations: it discloses the owner-only authorization requirement and the nature of the returned records (scoped, revocable credentials).

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

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

It is a single dense sentence with the resource and return fields front-loaded and the access constraint last. Nothing is redundant with the title 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?

There is no output schema, so the description correctly names the returned fields (label, agent type, scopes, status) and the access rule. For a zero-parameter read tool that is nearly sufficient; only pagination or result-size behavior is unaddressed, and with no parameters there is likely none.

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, so there is no parameter meaning for the description to explain. This is the 0-parameter baseline.

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

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

The description uses a specific verb and resource, 'List the workspace's DenkOps connection tokens', and then defines that resource as 'scoped, revocable agent/CLI credentials' with the fields label, agent type, scopes and status. This lets an agent understand what a connection is without opening other tools. It doesn't name a sibling to contrast with list_connector_accounts, so it stops short of 5.

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 the permission constraint 'Workspace owners only', which implicitly tells the agent when this call will succeed. It doesn't say when to use this rather than a sibling such as get_connection_activity or list_connector_accounts, and it states no exclusions, so the guidance is 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 value beyond them by naming the payload fields returned (next run, last run, status), which matters because there is no output schema. It stops short of pagination, ordering, or empty-result behavior.

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 sentence, front-loaded with the verb and resource, with the returned fields appended. No filler, no redundancy with the title 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?

For a one-parameter, read-only list tool with no output schema, the description conveys enough to call it correctly and previews what comes back. Minor gaps remain around result ordering, pagination, and behavior when no crons exist.

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 parameter with 100% schema description coverage, so the baseline is 3. The phrase "a project's" confirms the tool is scoped to project_id but adds no format, default, or constraint detail beyond the schema's pattern and description.

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

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

Specific verb + resource ("List ... scheduled (cron) jobs") with an explicit scope ("a project's managed"). It reads clearly apart from the mutating siblings run_cron and set_cron_enabled, though it never names them to sharpen the distinction.

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: an agent infers this is the read path for inspecting cron jobs, as opposed to run_cron (trigger) or set_cron_enabled (toggle). There is no explicit when-to-use, when-not-to-use, or prerequisite statement.

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 the safety profile is fully covered externally. The description adds only that results are "recent" and what fields come back, without defining the recency window, result limits, or pagination behavior.

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 the resource and scope stated first and the field list in a compact parenthetical. No sentence is wasted and there is no redundant restatement of the title.

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

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

With no output schema, the description does the necessary work of naming the returned fields (name, status, duration, span count). The only shortfall for a simple one-parameter list tool is the undefined recency window and result-size expectations.

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

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

With a single parameter and 100% schema description coverage, the schema already documents project_id and its pattern. The description adds no further meaning such as accepted id formats or aliases, 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?

"List recent request traces for a DenkOps project" gives a specific verb and resource with a clear scope, and the parenthetical enumerates the returned fields. It does not explicitly distinguish itself from the sibling get_trace, which is the only remaining ambiguity.

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: "List" versus the singular sibling get_trace suggests this is the browse-first call, but the description never says when to prefer one over the other. There is also no guidance on the meaning of "recent" or whether the result set is capped.

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, idempotentHint=true, and readOnlyHint=false, so the description is not obligated to restate safety. However, it adds nothing beyond the title: it does not say whether DNS records or TLS certs are released, whether traffic stops immediately, or whether the domain can be re-added.

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 no wasted wording. It is efficient, though the brevity borders on under-specification for a destructive operation.

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, irreversible-feeling mutation with no output schema, the description should state consequences and post-conditions (e.g., DNS/TLS teardown, effect on live traffic). Annotations cover the safety flag but not the operational impact, leaving a meaningful gap.

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

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

Schema description coverage is 100% with two well-documented required parameters (project_id, domain_id). The description adds no extra meaning about identifier formats or lookup behavior, 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 names a specific verb and resource ('Detach a custom domain') scoped to a 'DenkOps project', so the operation is unambiguous. It does not contrast with siblings such as add_domain, verify_domain, or list_domains, which keeps it from a 5.

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

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

There is no guidance on when to use this instead of alternatives (e.g., verify_domain first, or add_domain/add_domain to re-attach), and no stated prerequisites or warnings. An agent must infer everything about timing and sequencing from the name alone.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds two pieces of context the annotations do not: the revocation takes effect immediately (no grace period) and the caller must be a workspace owner, which is actionable auth information. It stops short of saying whether a revoked token can be restored or what happens to in-flight activity, 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?

Two short sentences with zero filler, and the core action plus the immediacy qualifier are front-loaded ahead of the permission constraint.

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 one-parameter destructive tool whose annotations already declare idempotency and destructiveness, the definition covers action, target, timing and authorization. The only material gap is the downstream consequence of revocation (whether dependent connections break or tokens can be reissued), which an agent might want before calling it.

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

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

Schema description coverage is 100% and the single parameter carries a documented pattern, so the schema already does the work. The phrase 'by its connection_id' only restates the parameter name and adds no format or sourcing detail. Baseline 3 is appropriate.

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

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

The description gives a specific verb plus resource ('revoke a DenkOps connection token') and names the identifier used to target it, so the operation is unmistakable. It doesn't explicitly contrast with adjacent siblings like regenerate_connection or update_connection_scopes, but the verb 'revoke' is distinct enough to separate it from listing or creation 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?

'Workspace owners only' establishes a prerequisite for use, which is real guidance. However, there is no explicit statement of when to choose this over regenerate_connection (rotate vs. kill) or what situation warrants immediate revocation, so the choice between siblings is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful fact beyond them — the invocation is recorded as a manual run, implying a persistent run record is created — but says nothing about what happens if the job is disabled or whether a run identifier is produced for follow-up.

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 the action first and the notable side effect in parentheses; there is no filler and nothing that could be trimmed 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?

For a two-parameter action tool with full schema coverage, explicit annotations, and no output schema, the description covers what the tool does and its main side effect. The remaining gap — whether a run handle is returned and how to observe the result — is modest but real for a fire-and-forget trigger.

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

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

Schema description coverage is 100% with only two required string parameters (project_id, job_id) carrying patterns, so the schema does the heavy lifting. The description adds no meaning about identifier formats or scoping beyond what the schema states; 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 names a specific verb ("Trigger") and resource ("managed scheduled job") and adds a scope qualifier ("immediately"), which separates it from list_crons (read) and set_cron_enabled (toggle). It stops short of naming those siblings, but the action is 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?

Usage is only implied: "immediately" and "manual run" suggest this is for forcing a run out of schedule, but the description never states when to prefer it over waiting for the schedule or over set_cron_enabled, nor any precondition such as the job needing to be enabled.

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 by disclosing the precedence gotcha ('A `branding` block in denkops.json overrides these values on the next deploy'), the permission requirement, and the automatic contrast behaviour for text colour. The destructiveHint=true edge is only implicitly covered by 'null resets to the DenkOps default' — it could say explicitly that clearing colours/icon is irreversible apart from re-setting them.

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

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

Three dense sentences, front-loaded with the action and facets, then update semantics, then prerequisites. No boilerplate or repetition 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?

For a 5-param mutation with no output schema, it covers everything an agent needs: what is mutated, which fields are optional, how to reset, size/format limits, permission gate, and the deploy-time override. Nothing material is left to guesswork.

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

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

With 40% schema coverage and two colour params carrying no schema description at all, the description does the compensating work: hex format example (#2563eb), null-reset semantics, accepted image MIME types, and the 2 MB cap. project_id and icon_mime_type are left to the schema, which is the right division, so this is close to full marks rather than deficient.

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 ('Brand a connector project's hosted sign-in and consent pages') and enumerates the exact settable facets (accent colour, background colour, icon). This is clearly distinguishable from the read-side sibling get_connector_branding 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 concrete preconditions ('Workspace owners only; the connector must be enabled') and partial-update semantics ('Omitted fields stay unchanged'), which tell the agent when the call is valid and what happens on repeat calls. It stops short of naming get_connector_branding as the way to inspect current values first, so the read-then-write workflow is only 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 the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description's job is to add context — and it does: it discloses that activation of routing is a side effect gated on the DNS record, and that a 'not-verified' outcome exists for propagation lag. It stops short of saying whether a failed check is retryable or whether anything is changed on failure, and the external DNS lookup sits oddly against openWorldHint=false, though this is not a direct contradiction.

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

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

Two sentences, zero filler, with the action and the activation effect front-loaded before the failure-mode note. Every clause carries information an agent needs.

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

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

For a simple two-parameter tool with full schema coverage and no output schema, the definition covers purpose, effect, and the main non-happy-path outcome. It is only slightly short on what a success response looks like and whether repeated calls are the intended recovery path for a not-verified result.

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 both domain_id and project_id are already documented with patterns and required status. The description adds no meaning beyond the schema — no hint about id formats, scoping, or how a domain_id is obtained (presumably from list_domains). 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 names a specific verb and resource ('Check a DenkOps custom domain's DNS TXT record') plus the resulting effect ('activate routing'), which cleanly separates it from siblings like add_domain, remove_domain, and list_domains. An agent can identify the operation 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?

Usage is only implied: the tool is clearly the post-DNS-configuration step, and 'Reports not-verified if the record isn't visible yet' hints at retry behavior. However, it never states prerequisites (domain must first be added via add_domain) or when not to call it (e.g., for non-custom or already-verified domains).

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 openWorldHint=false, so safety is well covered. The description adds only that the result includes both account and workspace scope; it says nothing about what data is returned, whether it can fail on an unauthenticated connection, or how it behaves with multiple workspaces. Useful but thin on top of already-rich 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?

A single front-loaded sentence with zero filler; the account-and-workspace scope is stated immediately and nothing repeats the title or name.

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

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

For a zero-parameter read tool with an output schema and full annotation coverage, the description covers what is needed to select and call it. It could be slightly stronger by noting this is the way to verify the active connection before other calls, but 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?

The tool takes zero parameters and the description correctly implies no input is required. With an empty schema there is nothing further to document, so the baseline of 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?

The description names a specific verb ('Show') and resource ('which DenkOps account and workspace this connection acts as'), which is distinct from siblings like get_workspace_overview or get_plan. It does not name a sibling explicitly, so it stops just short of a 5.

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

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

No explicit when-to-use or when-not-to-use guidance is given, and no alternative is named. Usage is strongly implied by the phrasing ('which ... this connection acts as'), making it easy to infer this is an identity/who-am-I check, but it is left to inference.

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