qrlia

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description goes well beyond them: it discloses that bot traffic (link previews, mail scanners) is excluded but surfaced in totals.botScans, that `days` is capped by the plan's analytics history (range.maxDays), and that Free plans return only totals and top QR codes with insights.included=false and an upgradeUrl.

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 returned metrics are front-loaded in the first clause, followed by bot-handling and plan behavior. It is dense and somewhat run-on, but every clause carries operational information rather than 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 and sparse parameter documentation, the description does the heavy lifting by describing the returned fields, the bot-exclusion rule, and degraded Free-plan output. The remaining gap is parameter interaction (qrId vs companyId) and whether `days` is relative to now.

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 only 25% (only includeBots is documented), so the description carries real weight — it supplies the default (30) and the plan-driven cap for `days`, and conveys that qrId/companyId narrow the scope to one QR or one company. It stops short of clarifying precedence or mutual exclusivity between qrId and companyId.

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+resource (scan analytics) and enumerates the exact outputs — totals, unique scans, daily series, top QR codes, geographic/OS/device/referrer breakdowns — so an agent can distinguish this aggregate view from raw-record siblings like scans_list or qrs_list 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?

Scope selection (workspace, one company, one QR) is implied through the described outputs and parameters, and the plan-tier caveat is spelled out. However, it never states when to prefer this over scans_list for raw records, nor how qrId and companyId interact when both are supplied.

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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful trait — statelessness ("Nothing is stored") — but says nothing about how the PNG is returned (bytes, base64, URL) or whether rate limits apply.

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

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

Two tight sentences with the capability front-loaded and no filler. Re-listing all ten enum values largely duplicates the schema, which costs a little density, but the sentence still 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?

With 7 parameters at 0% schema coverage and no output schema, the description should describe the return payload and at least the non-obvious inputs (e.g. color format, includeText behavior). It covers almost none of that, leaving the agent to infer invocation semantics.

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

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

Schema description coverage is 0% across 7 parameters, so the description must carry the burden and does not. It repeats the format enum already present in the schema and adds no meaning for data, scale, height, background, foreground, or includeText.

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 (Render), resource (1D / retail barcode), enumerates supported symbologies, and names the output artifact (PNG). Combined with the 1D/retail framing, an agent can distinguish it from the sibling qr_render_preview 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?

"Nothing is stored" implies this is the stateless rendering path as opposed to the persistent qrs_create* siblings, but no alternative is named and no when-not condition is given. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so the mutation and external-boundary profile is partly covered. The description adds valuable context beyond them: nothing is charged by this call itself and payment only occurs when a person opens the link.

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, purpose front-loaded, with the admin restriction and charging semantics following in order of importance. No wasted words, though 'upgrade from the free plan' is slightly narrowing context.

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

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

For a low-complexity two-parameter tool this covers the essentials, and there is no output schema to worry about. However it never states what is returned (presumably a link/URL) and leaves both parameters undocumented, so it is adequate but incomplete.

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

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

Schema description coverage is 0% and the description says nothing about either parameter. planSlug (the required field) and the cadence enum (monthly/annual) are left entirely to the schema's type/enum hints, so the description fails to compensate for the coverage gap.

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

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

States a specific verb+resource ('Create a hosted checkout link') with a clear qualifier ('to upgrade from the free plan'), which distinguishes it from the sibling billing_get. It does not name a sibling directly, but the checkout-link purpose 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?

Provides a real precondition ('Workspace admins only') and scopes the use case to upgrading from the free plan. It gives clear context but names no alternatives or explicit when-not 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the return contents (renewal/promo dates, limits), which is useful, but says nothing about auth requirements or response behavior beyond that.

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

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

A single dense sentence with no filler, front-loading the most important returned fields (current plan and status). 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?

With no output schema, the description carries the burden of describing returns, and it does list the key fields (plan, status, renewal date, features/limits, upgrade options). It is adequate for a zero-arg read tool, though it omits any mention of the checkout sibling as the natural next step.

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 no parameter semantics to document; the baseline for a no-param tool is 4. 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?

The description states the specific resource and scope (current plan, status, renewal date, features/limits, upgrade options), which clearly identifies it as a read of billing/plan state. It doesn't explicitly name the verb or differentiate from the sibling billing_checkout_link, which handles plan changes.

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 call this versus billing_checkout_link or other siblings. The phrase 'plans available to move to' hints that checkout is the follow-up action, but the routing condition is left entirely 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 this as a read-only, non-destructive, closed-world operation. The description adds that the brand kit includes approved designs and editor enforcement status, which gives some insight into returned content, but it omits permissions, error behavior, and anything about the companyId scoping.

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

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

The description is a single concise sentence with no wasted words. However, it is not front-loaded with the action an agent needs, so it is efficient but not optimally structured for selection.

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 one-parameter read tool, the title and annotations provide enough safety context to invoke it, and the description hints at returned content. Still, the required companyId is never addressed and there is no output schema to explain the return shape, leaving key invocation details incomplete.

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 0% description coverage and the description does not mention companyId or explain what identifier is required. With one undocumented parameter, the description fails to compensate for the schema gap.

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

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

The description names the resource ('company's approved designs') and includes useful detail about enforcement, but it is a noun phrase rather than an action statement. It never says 'get' or 'retrieve', leaving the operation implicit and not clearly distinguishing this from sibling brand_kit_set.

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 tool versus alternatives such as brand_kit_set. The description provides no context, prerequisites, or exclusions that would help an agent choose correctly.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real context beyond them: admin/plan gating, the enforcement effect on editors, and the default-design ordering. It does not state whether the existing kit is fully replaced, which is the main remaining 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 dense sentence with the resource action front-loaded and every clause carrying semantic or access information — no filler.

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

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

For a three-parameter mutation with no output schema, the description covers permissions, plan gating, param semantics, and enforcement behavior. It omits replacement/merge semantics and error behavior, but the caller has enough to invoke correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: it explains designIds ('saved design ids; the first is the default for new codes') and enforced ('whether editors are limited to them'). Only companyId is left implied, and the maxItems/format constraints remain in 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 ('Set a company's approved designs... and whether editors are limited to them') and clearly differentiates from the read-only sibling brand_kit_get. It even encodes the semantics of the designIds ordering.

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

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

Provides clear access context — 'Company admins; Team and Enterprise plans' — which tells the agent who can invoke it. It stops short of explicitly routing between this and brand_kit_get, but the set/get distinction is implied by the verb and sibling name.

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 readOnlyHint=false, but the description adds concrete context beyond them: the downstream effect that the company's QR codes stop being manageable, and the workspace-admin authorization requirement. It omits whether the archive is reversible, which is the key remaining behavioral question.

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 core action, then consequence, then permission constraint. No filler or repetition.

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

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

For a low-complexity destructive mutation with one parameter and no output schema, the description covers the action, effect, and permission model. It leaves unresolved whether archiving is irreversible and what happens to the company's other data, which matters given no unarchive sibling exists.

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

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

Schema description coverage is 0% for the single 'id' parameter, so the schema contributes only type and format. The description says nothing about the parameter at all, but with one self-evident company identifier the semantics are largely inferable, keeping this at a minimum-viable 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?

'Archive a company' gives a specific verb and resource that is plainly distinct from siblings like companies_update or companies_delete. It does not explicitly name or contrast with a sibling, but the action is unambiguous on its own.

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 (archive when a company should no longer be active) and the 'Workspace admins only' constraint scopes who may call it. There is no explicit when-to-use guidance or mention of alternatives such as companies_update.

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 openWorldHint=false, so the safety profile is covered structurally. The description adds one real behavioral constraint not present in annotations — the admin-only permission requirement — but says nothing about duplicate-name/slug handling, failure modes, or side effects, leaving meaningful gaps for a mutation 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 short sentences with zero filler: the action and resource are front-loaded, and the permission constraint follows. Nothing is repeated from 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 simple two-parameter create tool with full schema coverage and no output schema, the description covers purpose and access control, which is most of what an agent needs. It stops short of describing the created resource's response or duplicate handling, so it is not fully complete.

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%: both 'name' and 'slug' are documented in the schema, including that slug is auto-derived from name when omitted. The description adds no parameter-level detail beyond that, 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 ('Create a new company') plus the scope ('in the workspace'), which is enough to separate it from companies_update, companies_archive, and companies_get by action type. It does not explicitly contrast itself with those siblings, but the create verb 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?

The description gives a prerequisite ('Workspace admins only') that determines whether the agent may call the tool at all, which is useful gating information. However, it never states when to prefer this over alternatives such as companies_update (i.e. what to do if the company already exists), so usage 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful domain context about branding inheritance ('Its QR landing pages use that branding over the workspace's') but says nothing about permissions, error behavior when the id is unknown, or response shape.

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

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

Two tight sentences with the core operation front-loaded; the branding detail is placed after the primary action. No filler 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 no output schema, the description carries the burden of describing the return value and does so partially by listing branding fields (primaryColor, accentColor, logoUrl, fontFamily). Missing only edge-case behavior such as not-found handling, which is minor for a simple annotated read.

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

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

Schema description coverage is 0%, so the description must compensate for the single undocumented 'id' parameter. Saying 'by id' clarifies that the id identifies a company (versus some other entity id), which is marginally useful, but no format, validation, or lookup behavior is described beyond what the schema's uuid format already conveys.

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 one company by id'), and the word 'one' implicitly separates it from companies_list. It does not name a sibling alternative explicitly, but an agent can identify the operation unambiguously.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as companies_list or company_profile_get. The second sentence describes branding inheritance but does not help an agent decide when to call this tool rather than a sibling.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The phrase "that you can act on" adds a genuine behavioral detail about permission-based filtering, but nothing is said about pagination, ordering, or result size for a list operation.

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

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

A single short sentence with the core action front-loaded and no filler. It is efficient, though the trailing qualifier "that you can act on" is slightly vague and could be tightened.

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

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

For a zero-parameter list tool with safety annotations, the description is adequate but thin: with no output schema, the agent gets no indication of what each company entry contains or whether results are paginated. It covers the essentials without filling the remaining gaps.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to clarify; the baseline for a 0-parameter tool applies. No parameter detail is expected or missing.

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 (list) and resource (companies) with a workspace scope, which cleanly separates it from siblings like companies_get, companies_create, companies_archive, and companies_update. It is clear what the tool does, though it stops short of explicitly naming a sibling it contrasts with.

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?

"that you can act on" implies the listing is scoped to permissioned companies, giving an implicit sense of when the results are appropriate. However, there is no explicit when-to-use versus companies_get or companies_archive, and no stated prerequisites, so guidance 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real behavioral value beyond them: field-by-field merge semantics ('an absent field is unchanged, null removes it'), the fallback to the workspace value, and the downstream effect that QR landing pages render this branding on any host. It stops short of stating auth requirements or failure 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?

Front-loaded with the purpose in the first clause, then dense but purposeful detail. Every clause (merge rule, formats, rendering side effect) earns its place, though the second sentence runs long and packs several distinct rules into one block.

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 return-value burden but the update contract is otherwise well covered: merge semantics, null handling, field formats, and the branding side effect. Missing only error/invalid-input behavior and permission requirements for a nested-object mutation.

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 75% and the schema already documents hex format, the /uploads vs https rule, and CSS font lists, so much of the description's parameter detail duplicates structured data. The one genuinely additive rule, null means removed, is also already in the theme object's schema description. Baseline 3 is appropriate; little new meaning is contributed.

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 ('Change a company's name, status or branding') and enumerates the mutable surface, which is clear on its own. It does not, however, distinguish itself from siblings that touch the same data, notably companies_archive (which also changes status) and company_profile_update. A sibling-routing sentence is the only thing missing.

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 it should call this to mutate company fields. There is no explicit when-to-use versus companies_archive for status transitions, nor any mention of prerequisites or permissions. Adequate but with clear gaps for a mutation tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that this is a *public* profile view rather than internal company data, which is useful, but says nothing about auth requirements or what the returned profile excludes.

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 front-loaded sentence with the verb first and scope in a parenthetical; every word earns its place and there is no filler.

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

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

For a simple one-parameter read with full annotation coverage, this is serviceable, but the description is silent on two things an agent needs: how 'id' should be sourced, and how this differs from companies_get. No output schema exists, but that is mitigated because the parenthetical names the returned content.

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

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

Schema coverage is 0% and the single required 'id' (uuid) has no description in the schema. The phrase "a company's public profile" weakly implies the id identifies a company, but it does not confirm whether this is a company id, a domain, or another entity reference — a real ambiguity given the companies_* siblings.

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 (read) and resource (a company's public profile) and the parenthetical scopes what the profile contains (contact details, branding on landing pages). It is clear on its own, but it never distinguishes itself from the sibling companies_get, which an agent will plausibly consider the same resource class.

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 when-to-use or when-not-to-use guidance, and no alternative is named. The natural companion tools, companies_get and company_profile_update, are left for the agent to sort out by guessing from names 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 declare readOnlyHint=false and destructiveHint=false, so the write/safe-update profile is already covered. The description adds authorization context (admin scope), which is genuine value. But 'Replace' implies full overwrite semantics that sit awkwardly against the 'patch' parameter, a behavioral nuance the description never resolves.

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 followed by the permission constraint; nothing is padded. It is efficient, though its brevity contributes to the missing parameter and replacement semantics.

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

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

For a mutation tool with a deeply nested patch object, 0% schema coverage, no output schema, and a 'Replace' verb conflicting with patch semantics, the description omits the crucial partial-vs-full update question and any field-level guidance. Materially incomplete for correct invocation.

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

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

Schema description coverage is 0% and the patch object holds 15 nested fields, so the description carries the full burden. It says nothing about id, the patch object, which fields are settable, or whether this is partial vs full replacement - the exact ambiguity an agent needs resolved given 'Replace' vs 'patch'.

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 (replace a company's public profile), which is clearly a write operation distinguishable from the read sibling company_profile_get. However, it does not distinguish itself from companies_update or clarify how a 'company profile' differs from a 'company', leaving sibling routing to inference.

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

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

The 'Company or workspace admins' clause usefully signals the required permission level. But there is no explicit when-to-use versus alternatives (company_profile_get, companies_update) and no when-not guidance, so usage 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds meaningful context beyond that: access stops immediately, and self-disconnection terminates the current session. It omits auth requirements and behavior on invalid/unknown app ids.

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, each load-bearing: the action, its immediate effect, and the self-disconnect edge case. The critical session-ending warning is front-loaded and wastes no words.

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

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

For a simple destructive one-parameter tool with no output schema, the description covers the action and its most consequential side effect. The main gap is failure behavior (e.g., disconnecting an app that isn't connected) and disambiguation of the id parameter.

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 one required parameter (id) with 0% schema description coverage, so the description must carry the burden of explaining it. It never identifies what 'id' refers to (app id, connection id?) or its format, leaving the sole parameter semantically undocumented.

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 ('Disconnect an app you connected'), which is unambiguous. It does not explicitly differentiate itself from the only related sibling (connected_apps_list), though the verb contrast makes the distinction obvious.

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

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

There is no explicit when-to-use or when-not-to-use guidance versus alternatives, but the caveat 'Disconnecting the app you are using now ends this session' functions as an implied usage precondition. The agent can infer context but is not told the conditions that select this tool over others.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds valuable context beyond annotations by specifying that these are OAuth-connected apps and that the response includes scopes and last use, which helps the agent understand the returned 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?

The description is a single, front-loaded sentence that packs all necessary information without any wasted words. It is appropriately sized for a simple list 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?

Given the zero-parameter schema, the rich read-only annotations, and the absence of an output schema, the description is complete enough. It tells the agent what kind of apps are listed and what fields (scopes, last use) are included, which is sufficient for correct invocation and interpretation.

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 parameter semantics baseline is 4. The description does not need to explain any parameters, and none are present in 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 states a specific verb (implied by title 'List') and resource ('connected apps') and elaborates on exactly what is returned: OAuth-connected apps including Claude, Claude Code, and other MCP clients, with scopes and last use. It is easily distinguishable from the sibling connected_apps_disconnect, which performs a different action.

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 usage by describing what is listed, so an agent can infer it is for viewing connected apps. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide any exclusions or 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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is covered. The description adds the persistence-for-reuse relationship and the designId linkage, but says nothing about required permissions, plan limits (e.g. hideLogo not on Free), or what happens on name collisions.

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, zero filler, and the core action is front-loaded before the designId linkage. Nothing to trim.

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?

No output schema exists, so the description carries the return-value burden; it only indirectly implies a designId is produced. For a tool with a large nested spec object and no return documentation, the description is adequate but leaves key gaps (return shape, error/limit behavior).

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 50%: the spec object is documented exhaustively in the schema, but the required 'name' parameter has no description anywhere. The description only points out that spec fields match a preview design, adding a useful cross-reference but not compensating for the undocumented name semantics (uniqueness, reuse constraints).

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

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

States a specific verb and resource (save a QR design for reuse) and ties it to how QR codes consume it via designId, which separates it from designs_update and qrs_create. Sibling differentiation is implicit rather than explicit, but an agent can identify the tool's role.

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 phrase 'for reuse' plus the designId reference implies you create a design once and attach it to QR codes, giving usable context. However, there is no explicit when-to-use versus designs_update/templates_create, and no prerequisite or exclusion 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: no statement that deletion is permanent/irreversible, no permission requirements, and no note on side effects such as whether rendered QRs or analytics tied to the design are affected.

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 short sentence with no padding and the action front-loaded. It is efficient, though the brevity comes at the cost of substance rather than being genuinely tight.

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 no output schema and an undocumented parameter, the description is far too thin. It omits irreversibility, auth requirements, and the identifier needed to invoke it, leaving an agent to guess at the consequences of 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?

The schema has 1 parameter with 0% description coverage, so the description must compensate and does not. It never mentions the required 'id' argument or its UUID format, leaving the schema's bare type declaration as the only documentation.

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

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

States a specific verb (Delete) and resource (a saved QR design), which is enough to tell it apart from designs_get, designs_list, designs_update, and designs_create. It does not explicitly name those siblings or scope, but the name-plus-description combination 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?

No guidance on when to use this versus designs_update or designs_list, and no mention of prerequisites or exclusions. The agent must infer everything from the tool 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 readOnly=true, destructive=false, and openWorld=false. The description adds no behavioral context beyond restating a read operation: no auth requirements, not-found behavior, or scoping details.

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 short, front-loaded sentence with no filler. Every word contributes to the core action.

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

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

For a simple read-by-ID tool whose annotations cover the safety profile, the description conveys the essential action. It still omits parameter meaning and, with no output schema, any expectation of what is returned, leaving gaps for confident invocation.

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

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

The single parameter id has 0% schema description coverage. The description does not mention id, its UUID format, or that it selects which saved design is returned, so it fails to compensate for the missing schema documentation.

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

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

States a specific verb ('Read') and resource ('saved QR design'), and 'one' distinguishes it from designs_list. It does not explicitly name a sibling alternative, so it stops short of the 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?

There is no when-to-use guidance, no alternative named, and no prerequisites. The agent must infer retrieval-by-ID solely from the name and the surrounding designs_* siblings.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only that a design comprises colours, shapes, logo and frame, which is resource composition rather than behavior; it says nothing about ordering, pagination or result limits for a collection endpoint.

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 short sentence with the key noun ('saved QR designs') front-loaded and the parenthetical attributes kept brief. No filler or redundancy.

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

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

With no parameters and no output schema, the description carries the burden of hinting at the return shape; the parenthetical field list partially does this, but an agent still cannot tell whether the response is paginated, sorted, or scoped to a workspace. Adequate but with a clear 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?

The tool takes zero parameters and the schema is empty, so there are no parameter semantics to explain. Baseline 4 applies; the description correctly avoids inventing inputs that do not exist.

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 ('List saved QR designs') and scopes it with the design attributes it returns, which is enough to distinguish it from designs_create/delete/update by name. It does not explicitly contrast itself with designs_get, but the plural 'List' plus 'saved' makes the intent clear.

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

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

There is no guidance on when to use this versus designs_get or the other designs_* siblings, nor any note about prerequisites or filtering. Usage is only implied by the verb 'List'.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot: 'Every QR code using it renders with the new look,' disclosing the cascading, multi-object impact of the edit. It does not, however, say whether the change is reversible, whether omitted fields are preserved, or how quickly re-rendering propagates.

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 padding: the mutation is front-loaded and the consequence follows immediately. Nothing is repeated from the title or the schema, and both sentences earn their 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 nested-object mutation with no output schema, the description covers purpose, the whole-spec replacement semantics, and the cross-object render impact. It stops short of stating the return payload, whether id/name updates are partial-merge or replacement, or any plan restriction (which is buried in the nested schema instead).

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?

Top-level schema description coverage is only 33% (id and name carry no description), so the description has to compensate. It partially does by mapping 'rename' to name and 'replace its spec' to spec, and by making clear the spec is substituted wholesale rather than merged. The deep spec semantics live in the schema's own nested description, not the tool description, so this stays at baseline.

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

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

The description states specific verbs and the resource: 'Rename a design or replace its spec.' That pairs the two mutation modes with the two writable fields and is clearly distinguishable from designs_create, designs_get, and designs_delete. It even states the downstream effect, which no sibling shares.

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 tool for modifying an existing design, and 'rename or replace spec' hints at the two supported cases. There is no explicit when-to-use guidance, no mention of when to prefer designs_create (for a fresh lookalike), and no prerequisites such as ownership or plan limits.

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 safety profile (readOnly=false, destructive=false, openWorld=false), so the bar is lower. The description adds genuine behavioral context beyond the annotations: the domain starts unverified, it returns the DNS TXT record needed for ownership proof, and verification completes once that record is published.

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 sentence with the core action front-loaded ('Bind a custom domain') followed by the essential lifecycle detail. No wasted words.

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

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

For a 3-parameter mutation tool with full schema coverage and annotations covering the safety profile, the description supplies the key missing piece: the unverified-state lifecycle and what the call returns. It does not address duplicate-host or permission behavior, but nothing critical for correct invocation 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 the schema fully documents host, role, and companyId. The description adds no parameter-level meaning beyond what the schema already provides, making the baseline 3 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 ('Bind a custom domain'), which is clearly distinct from domains_delete, domains_update, and domains_list. It does not explicitly name the nearest sibling (domains_verify), though the mention of the verification flow hints at the relationship.

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 guidance or exclusions are provided. The description does not tell the agent when to reach for domains_create versus domains_update or domains_verify, leaving 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 destructiveHint=true and readOnlyHint=false, so the bar is lower, yet the description adds genuinely new behavioral context: QR codes on the domain stop resolving. It does not say whether the unbinding is reversible, whether the QR codes themselves are deleted, or what permissions are required.

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 terse sentences with no filler, and the core action is front-loaded ahead of the consequence. Nothing needs to be cut.

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 no output schema this covers the essential effect on downstream QR codes, but leaves open irreversibility, permission requirements, and whether the domain record is removed or merely unlinked. Adequate but with clear gaps for a one-way 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 description coverage is 0% and the description does not mention the single 'id' parameter at all. The agent must infer from the schema name and uuid format that this is the domain identifier; the description contributes no compensating semantics.

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

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

States a specific verb (unbind) and resource (custom domain), and distinguishes itself from siblings like domains_update, domains_verify, and domains_list by describing removal. The second sentence clarifies the scope of the operation's effect.

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 when-to-use guidance and no named alternatives; the description never says whether to prefer domains_update for configuration changes or how this differs from other domains_* operations. The consequence sentence hints at the decision context but stops short of explicit routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the useful scope fact that only custom domains bound to this workspace are returned, but says nothing about ordering, pagination, or pending/violating domain states.

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 filler. Every word (custom, bound, this workspace) constrains the result set and 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 zero-argument read tool with annotations covering the safety profile, the description is nearly sufficient. With no output schema, a hint about what a domain entry contains (verification status, hostname) would have closed the last 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter gaps exist to compensate for.

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 (List) and resource (custom domains) with a scoping qualifier ('bound to this workspace'), so an agent knows exactly what is returned. It does not, however, distinguish itself from the sibling domains_verify or contrast with domains_create/update/delete, so it is clear but not sibling-differentiating.

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 when-to-use guidance and no reference to alternatives. The agent must infer from the name alone that this is the read path for the domains_* family rather than domains_verify or domains_update.

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 openWorldHint=false, so the safety profile is known. The description usefully narrows the mutation scope to primary status and role, but omits meaningful side effects an agent would want to know, such as whether setting a new primary demotes the existing one or what role changes imply for live traffic. Given annotation coverage, a 3 is appropriate.

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 verb and the two supported actions; there is no filler or redundancy.

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

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

For a mutation tool with no output schema and only 33% parameter coverage, the description is serviceable but thin: it never says what happens to the previously primary domain, whether authorization is required, or what the call returns. It is adequate to call the tool but leaves real gaps.

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

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

Schema description coverage is only 33%: role carries a rich enum description in the schema while id and isPrimary are undocumented. The description partially compensates by mapping its two stated operations onto isPrimary ('make primary') and role ('change its role'), but adds no format or constraint detail for id or isPrimary.

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 (update) and resource (domain) and names the two operations the tool supports: promoting a domain to primary and changing its role. This is distinguishable from the sibling domains_create/delete/list/verify, which do different things. It falls short of a 5 only because it does not explicitly contrast itself with domains_verify, which also touches an existing 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?

There is no guidance on when to use this tool versus the alternatives (domains_verify for verification, domains_create for adding a domain, domains_list for reading). The two supported operations are implied by the sentence but no preconditions or context for choosing this tool 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?

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the mutation-plus-external-lookup shape is covered. The description adds real value by naming the mechanism (TXT record check) and the side effect (marking verified on success), which annotations do not convey. It omits failure behavior and idempotency, so it stops short of a 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?

A single twelve-word sentence, front-loaded with the action and its outcome. Every clause carries information; nothing is padded.

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?

No output schema exists, so the description should carry more of the interaction contract. It covers the success path but says nothing about what happens when the TXT record is missing or wrong, nor whether the agent should retry after DNS propagation. Adequate but with a meaningful gap for an open-world verification 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?

One required parameter with 0% schema description coverage, so the description carries the burden. 'The domain's' implies the id parameter identifies a domain to verify, but gives no format or sourcing detail (e.g. whether it is the domain record id or the hostname). Marginal help over a bare uuid-typed id.

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 pair twice over: check the domain's TXT record, then mark it verified. An agent can distinguish this from domains_update or domains_list. It does not name a sibling alternative, 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?

No guidance on when to call this versus domains_update, nor any prerequisite stated (e.g. that the TXT record must already be published and propagated). The agent gets the mechanism but not the conditions under which this tool is the right choice.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two genuinely useful behavioral facts: the response includes aggregate totals/average and that pagination is cursor-based. It omits ordering, default limit, and page-size behavior, so it adds value but stays thin.

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 compact clauses with zero filler, and the content description is front-loaded before the pagination note. Every word 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?

For a simple read-only list tool with no output schema and annotations covering safety, the description tells an agent what comes back and how paging works. However, with 0% parameter documentation it should have said more about qrId, limit defaults, and result ordering to be fully self-sufficient.

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

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

Schema description coverage is 0% across three parameters (qrId, limit, cursor). The description only alludes to the cursor parameter via 'Cursor-paginated' and says nothing about qrId's role or limit's bounds (schema caps it at 200), so it fails to compensate for the schema gap.

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

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

Names the resource precisely (ratings and comments on a feedback QR's page) and states the returned aggregate (total and average rating), which goes beyond a bare 'list feedback'. It does not explicitly differentiate itself from near-siblings like scans_list or leads_list, but no sibling covers this resource, so confusion risk is low.

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 when-to-use guidance, no prerequisites (e.g. that an existing QR with feedback is required), and no mention of alternatives. The only usage hint is the trailing 'Cursor-paginated', which implies how to iterate but not when to call the tool or how to start the cursor.

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 openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say whether names must be unique, whether creation is repeatable/idempotent, what happens on duplicate names, or what the caller gets back.

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, which is structurally sound. However, brevity here borders on under-specification for a tool that has real unknowns (naming rules, permissions, return value), so it earns only a middling score.

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

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

For a simple 2-parameter mutation with no output schema, the description leaves the agent without naming constraints, permission requirements, duplicate-handling behavior, or any indication of the created folder's identifier. Annotations cover only the generic write-safety profile, so the gaps remain.

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 only 50% — companyId is documented inline (including the active/pinned company default) but name has no description at all. The description mentions "company" only obliquely and says nothing about the name parameter's constraints or the 1–60 character limit, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource ("Create a QR folder") plus its scope ("in a company"), which is enough to separate it from folders_delete, folders_rename, and folders_list. It does not explicitly name those siblings or state how it differs from them, so it stops 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?

There is no when-to-use guidance, no prerequisites (e.g. permissions or plan requirements), and no reference to alternatives such as folders_rename or nesting under an existing folder. The agent must infer everything from the one-line purpose.

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, readOnlyHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely non-redundant behavior: the folder is destroyed but its contained QR codes survive and are re-parented to the company root. It omits permission requirements and whether the delete is reversible.

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, zero filler, with the primary action front-loaded and the consequential side effect immediately after. 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 single-parameter destructive delete with no output schema, the description covers the one thing an agent cannot infer: what happens to the folder's contents. Remaining gaps (auth scope, failure modes) are minor against annotations that already flag destructiveness.

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 (a UUID 'id') exists and schema description coverage is 0%, so the description carries the burden but never mentions the identifier at all. The parameter is self-evident from its name and type, so this is a minor gap rather than a serious one.

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 ('Delete a folder') and adds the crucial scoping detail that QR codes inside are preserved and relocated to the company root, which effectively separates it from qrs_delete and folders_rename. It does not name a sibling explicitly, so it falls just short of the top band.

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 side-effect note ('codes are kept and move back to the company root') tells an agent this is a safe non-cascading delete, which informs the decision. However there is no explicit when-to-use, when-not-to-use, or alternative (e.g. folders_rename for reorganizing) 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the '(plan feature)' note (a hint at entitlement gating) and the data-model fact that a code's folder is its folderId. It says nothing about pagination, ordering, or return format, so the added value beyond annotations is modest.

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

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

Two short sentences, purpose front-loaded, no filler. The parenthetical '(plan feature)' is slightly compressed and ambiguous, but overall the sizing is appropriate for a simple list tool.

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

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

For a read-only list tool with annotations covering safety and no output schema, the description roughly covers what is returned (folders plus code counts). However it leaves the companyId parameter unexplained and gives no sense of ordering or completeness of the result set, so gaps remain.

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

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

Schema description coverage is 0% for the single companyId parameter, and the description never mentions it. With one optional scoping parameter and no schema documentation, the description should compensate for the gap but does not, leaving the agent unsure how company scoping affects results.

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 ('List QR folders') plus scope detail ('with how many codes each holds'). An agent can distinguish this from folders_create/delete/rename by the listing verb. It stops short of explicitly naming those siblings as non-alternatives, so it's clear but not maximally differentiated.

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?

Listing folders is self-evidently the right call when you want an inventory, so usage is implied rather than stated. There is no explicit when-to-use guidance, no note on when to prefer other folder tools, and no exclusions. The '(plan feature)' parenthetical hints at entitlement gating but doesn't frame usage.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: no idempotency note, no permission requirements, no statement about whether the old name is preserved or history is affected. For a mutation tool it leaves the behavioral surface essentially undocumented.

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 short, front-loaded sentence with zero padding. However, the brevity stems from under-specification rather than disciplined editing, so it is adequate but not exemplary.

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 two required parameters, no output schema, and no annotations describing error or permission behavior, the definition leaves an agent without enough context to invoke it confidently in edge cases (nonexistent id, duplicate name, length limits). More detail is warranted at this complexity.

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

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

Schema description coverage is 0%, so the schema only conveys type/format constraints (uuid id, 1-60 char name) without semantic meaning. The description does not explain which folder 'id' refers to, whether 'name' must be unique within a workspace, or what happens on invalid input, so it fails to compensate for the coverage gap.

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

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

The description states a specific verb (rename) and resource (QR folder), which clearly distinguishes it from folders_create, folders_delete, and folders_list. It stops short of explicitly contrasting with those siblings, but the intent 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?

There is no guidance on when to use this versus folders_create or folders_delete, no prerequisites (e.g. folder must already exist), and no mention of what happens on a name collision or length violation. The agent must infer everything from the tool 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, closed-world), so the bar is lower; the description still adds real value by disclosing the auth requirement (OAuth only, API keys cannot manage keys) and that key creation is web-only and shown once. It omits pagination or result-size behavior, which is the remaining 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?

Three tight, front-loaded sentences with no filler; the listing scope leads and the constraints follow. The final clause about keys being shown once is peripheral to a listing operation and slightly exceeds what is needed here.

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 compensates by naming the returned fields (name, prefix, company, last use), and it covers auth prerequisites and the absence of an API-side key-creation path. For a zero-parameter read tool, nothing an agent needs before calling 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 the baseline is 4. The description cannot add parameter meaning, and it correctly does not invent any; it instead enumerates the returned fields, which is useful although not a parameter concern.

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 ('List the workspace's API keys') and immediately names the return fields (name, prefix, company, last use). It also implicitly separates itself from the only other key tool, keys_revoke, and from non-existent create/update key tools by stating keys are created only in the web app.

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 operating context: it works over a signed-in (OAuth) connection and an API key cannot manage keys, plus it redirects key creation to the web app. It does not explicitly name keys_revoke as the alternative for key lifecycle operations, so the when-not guidance is present but not fully routed.

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 readOnlyHint=false, but the description adds real value beyond them: the breakage is immediate ('stop working at once') and revocation is limited to OAuth/signed-in credentials. It omits whether revocation is permanent or whether keys can be re-created to restore access.

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 filler, with the action and its blast radius front-loaded. Every clause carries information an agent needs before calling a destructive tool.

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

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

For a one-parameter destructive tool with no output schema, the description covers impact and authorization scope adequately, and annotations carry the safety profile. The only meaningful hole is provenance of the 'id' value.

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

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

Schema description coverage is 0% and the single required parameter 'id' is never mentioned in the description. The schema supplies type and format but nothing links the id to a key obtained via keys_list, so the description fails to compensate for the coverage gap.

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

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

States a precise verb (Revoke) and resource (API key), and adds the scope constraint 'Signed-in (OAuth) connections only'. An agent can immediately distinguish this from the sibling keys_list, which reads rather than mutates.

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 operative precondition for use ('Signed-in (OAuth) connections only') and the consequence that selects careful use ('Scripts and integrations using it stop working at once'). It never names a sibling or an explicit when-not, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no statement about permanence/irreversibility, confirmation requirements, or permission scope — so it does not earn credit for extra behavioral 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?

A single tight sentence with the action front-loaded and the motivating scenario appended. Nothing is wasted, though it is sparse enough that the brevity edges into under-specification.

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 destructive tool with annotations covering the safety profile and no output schema, purpose and a use case are present. The unresolved gap is parameter meaning, which is documented nowhere in the description or 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 0% and the description never explains qrId or leadId. A reader can only infer that 'one lead-form submission' corresponds to a single leadId scoped under a qrId; there is no format, source, or lookup guidance to compensate for the undocumented 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 ('Delete one lead-form submission'), which cleanly distinguishes it from leads_list and other read siblings. It is clear but does not explicitly name the sibling it is not, 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?

Provides one concrete trigger ('when the person asks to be removed'), which implies when to reach for it, but gives no when-not conditions, prerequisites, or explicit alternative (e.g., leads_list for inspection first). Usage is implied rather than prescribed.

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 this safe and read-only, but the description adds genuinely useful context beyond them: the exact nature of the payload (owner-defined fields plus accepted consent text), a personal-data handling warning, and the pagination model. It does not describe default limits or ordering, which limits 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?

Three tight fragments with no filler, and the resource identity is front-loaded before the privacy note and pagination hint. The telegraphic style is slightly clipped but nothing 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 no output schema, the description usefully characterizes the return payload and pagination, and flags the sensitivity of the data. It is reasonably complete for a read-only list tool, though undocumented parameters and an unstated default page size leave minor gaps.

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

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

Schema coverage is 0% – qrId, limit, and cursor carry no descriptions anywhere. The description only gestures at pagination ('Cursor-paginated'), giving no meaning for the required qrId or the limit bounds, so it fails to compensate for the documentation gap.

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

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

The description names the concrete resource ('submissions from a lead_form QR's page') and enumerates the key content (owner-defined fields plus consent text), so an agent knows exactly what is returned. It stops short of explicitly contrasting with siblings such as leads_delete or scans_list/feedback_list, so differentiation is left to inference.

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

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

There is no when-to-use statement, no prerequisites, and no mention of the related leads_delete sibling or any alternative for retrieving lead data. The only faint usage cue is 'Cursor-paginated', which describes mechanics rather than selection 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value beyond that: the auth-model constraint (OAuth vs API keys) and the fact that 'email' is read-only even though the tool is a getter.

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 compact clauses, front-loaded with the payload then the access caveat. No filler sentences and nothing repeated from annotations or 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?

With no output schema, the description compensates by enumerating the returned fields and the access precondition, which is everything needed to call a parameterless identity endpoint correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly focuses on the return payload instead of inventing input semantics.

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

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

States a specific verb+resource ('Your own profile') and enumerates the exact fields returned (name, photo, theme, email, role, workspace). 'Your own' implicitly separates it from the sibling company_profile_get, 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?

Gives a concrete applicability condition: 'Signed-in (OAuth) connections only; API keys have no user,' which tells the agent when this call is valid. It does not name me_update or company_profile_get as alternatives, so routing is left partly 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered and the description correctly does not contradict it. The description adds the behavioral constraint that the target must already be a workspace user. It does not disclose whether an invitation email is sent, what happens if the user is already a member, or whether the action is idempotent.

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 compact sentence with no filler, and the key scoping constraint ("existing workspace user") lands early. It is efficient, though the title restates the same intent, so the sentence does not carry much extra payload.

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 three-required-parameter mutation tool with no output schema, the description is thin: it omits whether an invite/notification is sent, behavior on duplicate membership, and how this differs from members_set_role. An agent has enough to attempt the call but not enough to predict its consequences.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it only loosely gestures at the three parameters (company = companyId, user = email, "given role" = role). It adds no format, constraint, or semantics for email/companyId and never explains the role enum values, so the schema is not meaningfully supplemented.

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 action and resource: granting an existing workspace user access to a company at a given role. The phrase "existing workspace user" usefully distinguishes it from creating a user. However, it never differentiates itself from close siblings like members_set_role or members_remove, which an agent must disambiguate on its own.

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 a precondition ("existing workspace user"), which tells the agent this is not a user-creation path, but it gives no explicit when-to-use guidance and never names the alternative members_set_role, which appears to overlap heavily. 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only that roles are included in the result, but says nothing about pagination, result size, or whether archived/suspended members appear, which for a read listing tool would be genuinely useful.

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 waste, correctly leading with the action and the returned entity. It is terse to the point of omitting useful detail, but nothing present 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 one-parameter read-only listing with annotations covering safety and no output schema, the description is minimally adequate but leaves the required identifier unexplained and gives no sense of result shape beyond 'roles'. A sentence on what a member record contains or how results are scoped would close the 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 0% and the single companyId parameter carries no description in the schema. The description refers vaguely to 'a company' but never explains that companyId is the required UUID identifier, so it fails to compensate for the coverage gap.

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

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

States a specific verb (list) and resource (people who can access a company) plus a scope hint ('with their roles'). The 'list' verb naturally separates it from members_invite/members_remove/members_set_role, though it never names those siblings 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?

No when-to-use guidance, no prerequisites, and no mention of the sibling tools (members_invite, members_remove, members_set_role) that an agent must choose between. The agent must infer routing entirely from the verb.

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, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the nuance that it removes 'access to a company' (i.e., membership revocation) rather than deleting the user, which is useful but does not cover reversibility, permissions, or side effects.

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

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

The description is a single, front-loaded sentence with zero waste. It delivers the core action immediately and is appropriately sized for a simple tool.

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

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

For a low-complexity removal tool with annotations covering destructiveness and no output schema, the description is minimally adequate. However, with 0% parameter coverage, it should have clarified required identifiers or any operational prerequisites, leaving a clear 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 0%, so the description must compensate, but it only implicitly maps 'a person' to userId and 'a company' to companyId. It provides no format, constraint, or identifier details beyond what the schema names already suggest.

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

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

The description states a clear verb ('Remove') and resource ('a person's access to a company'), making it easy to distinguish from members_set_role or members_invite. However, it does not explicitly name or contrast with any sibling tool, so it falls short of the 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 description offers no guidance on when to use this tool versus alternatives like members_set_role or members_invite. It merely restates the action without context, exclusions, or prerequisites.

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 openWorldHint=false, so the basic safety profile is covered. The description adds nothing beyond that: it does not say whether elevated permissions are required, whether the affected member is notified, or that assigning company_viewer can revoke existing access. With annotations present the bar is lower, but this text contributes no behavioral 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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity stems partly from under-specification rather than disciplined editing.

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

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

This is a mutation tool with three required parameters, 0% schema description coverage, and no output schema. The one-sentence description leaves permission requirements, side effects on the target member, and confirmation of the change entirely undocumented, which is inadequate for a role-mutating 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 description coverage is 0%, so the description must carry parameter meaning, but it only gesturally covers 'role' and 'company'. It never mentions the userId parameter or the required UUID formats, and the enum values exist only in 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 ('Change') and resource ('a member's role in a company'), so an agent knows exactly what the operation does. It does not differentiate itself from nearby siblings like members_invite or members_remove, which also touch member membership, leaving the boundary to be inferred from the name alone.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as members_remove for removing rather than reassigning a member. Usage is only implied by the tool name.

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 this is a write operation (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds valuable context beyond annotations: supported formats, a 2 MB size cap, two input sources (dataBase64 or public HTTPS sourceUrl), authentication requirement, and that it returns the updated profile. It does not clarify whether an existing avatar is overwritten or describe failure modes, so it falls short of a perfect 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 tightly written sentences with no wasted words, front-loading the core action and constraints before the authentication note. 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 3-parameter mutation tool with no output schema, the description covers input formats, size limit, source options, auth requirement, and return value at a high level. It could be more complete by clarifying overwrite behavior and failure handling, but it gives the agent enough to call the tool correctly.

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

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

Schema description coverage is 67%, with contentType and sourceUrl documented in the schema and dataBase64 undocumented. The description adds meaning by listing accepted image types and the 2 MB limit, and clarifies that either dataBase64 or sourceUrl is used, but it does not explain the base64 encoding expectation or how sourceUrl/contentType interact.

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 (upload and set) and a specific resource (profile photo / your photo) in one step. It clearly differentiates the tool from general profile update siblings like me_update by focusing exclusively on the avatar.

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 usage (setting a profile photo) and gives a clear precondition: 'Signed-in (OAuth) connections only.' However, it does not explicitly say when to use this tool versus alternatives such as me_update, leaving usage guidance at an implied level.

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 readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds real context beyond them — the email field is immutable and billed, photo removal is destructive-by-null, and OAuth-signed-in connections are required. It does not say whether omitted fields are left unchanged, which matters for a partial-update mutation.

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 what can be changed and followed by constraints and routing. Every sentence earns its place, though the theme enum duplication is slightly 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?

With no output schema, the description still covers the mutable surface, the immutable field, the auth prerequisite and cross-tool routing. The only meaningful gap is partial-update semantics — whether passing a single field leaves the others intact.

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

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

Schema description coverage is 100%, so the schema already documents name, theme and avatarUrl including the null semantics ('null to remove the photo'). The description mostly restates this, adding only the enum values and null-removal behavior that the schema itself already carries, 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?

Opens with a specific verb+resource ('Change your name, theme ... or photo') and enumerates the exact mutable fields with the theme enum inline. It also distinguishes itself from me_set_avatar by explicitly delegating photo uploads there, so an agent can tell the two apart 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 routes to the sibling tool for a new photo ('For a new photo use me_set_avatar'), states how to remove one ('pass avatarUrl null'), rules out a field ('Email cannot be changed'), and gives an auth precondition ('Signed-in (OAuth) connections only'). When-to-use, when-not-to, and the alternative are all present.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the meaningful behavioral fact that the operation persists nothing, which reinforces the preview-only contract beyond what annotations state.

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 packed sentences with no filler; the operation, its content kinds, its design scope and its non-persistence are all front-loaded.

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

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

There is no output schema, and the description never states what a preview returns (image bytes, a URL, or a rendered document keyed off the png/svg format enum). For a render tool with nested design/payload objects and no output schema, that return-value gap is the main missing piece.

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 67% and the design object is already documented in the schema. The description compensates by enumerating the accepted payload kinds (url, text, email, phone, sms, wifi, whatsapp, geo, event, vcard), which the schema only gestures at with a single 'kind' example, adding real selection value.

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 ('Render') and resource ('unsaved static QR') and enumerates the ten supported content kinds plus the design aspects being tried (colours, shapes, logo, frame). 'Unsaved' / 'Nothing is stored' implicitly distinguishes it from qrs_create and qrs_get_image, though no sibling is named outright.

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 phrase 'to try colours, shapes, logo and frame' implies the preview-before-commit use case, and 'Nothing is stored' signals it is a dry run. However, it never explicitly says when to prefer this over qrs_create or qrs_create_from_template, so the routing 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 a non-destructive, closed-world write, so the bar is lower; the description still adds real behavior beyond them: the 200-row limit, the paid-plan requirement, per-row partial failure, and the `ok` field in each result. Missing detail on rate limits or ordering of results.

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 core capability and limit, then the row contract, then failure semantics. 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?

With no output schema, the description covers the essentials an agent needs: batch size, plan gate, row semantics, and partial-failure reporting via `ok`. Could be complete by noting ordering or how to identify which rows failed.

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 row shape is spelled out in the schema itself, so the baseline is 3. 'Each row takes the same fields as a single create' restates what the schema already documents and adds no new syntax or constraints.

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

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

States a specific verb and resource plus the batch scope and hard ceiling ('Create up to 200 QR codes in one call'). This implicitly separates it from qrs_create/qrs_create_url, though no sibling is named 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?

Gives one gating prerequisite ('paid plans') and implies the bulk use case, but never states when to prefer this over qrs_create or what to do for a single code. Usage is implied rather than directed.

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 the safety profile (not read-only, not destructive, closed-world), so the description only needs to add operational context. It adds that the code is created in a folder/company and returned with a short link, which is useful, but omits that some types are static with no short link, that smart-redirect rules are plan-gated, and that landing-page codes show a consent page before redirecting.

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 second sentence is tight and front-loads the scoping/return facts, but the first sentence spends most of its length enumerating 24 type values that the schema enum already lists, which is redundant rather than informative. No structural flaw, but meaningful waste.

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 10-parameter tool with nested objects and no output schema, the description does state the return value, which is otherwise undocumented. However it says only "Returns the code with its short link", which is incomplete and arguably misleading for the static types the schema says have no short link, and it leaves the uploads_create dependency and plan gating to the 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 90%, so the schema already documents type, access, content, tracking, designId, folderId and companyId in detail. The description's only parameter-level contribution is restating the type enum and naming design/folder/company, which is already covered; 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 ("Create a QR code") plus the supported type set, scoping constraints (design, folder, company) and the return (short link). It does not distinguish itself from close siblings such as qrs_create_url, qrs_create_from_template or qrs_bulk_create, so an agent cannot tell from the description alone when this general tool is preferred.

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?

"of any type" implicitly positions this as the general-purpose creator versus the type-specific sibling qrs_create_url, but the routing is left to inference. There is no explicit when-to-use/when-not-to-use statement, no mention that url codes are the ones needing targetUrl/rules, and no mention of the uploads_create prerequisite.

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 openWorldHint=false, so the safety profile is covered. The description adds useful behavior — template type/defaults are inherited and payload overrides fields — but says nothing about what is created, where it lands, or failure modes.

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

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

Two sentences, front-loaded with the action and scope, with no filler. Every clause carries information about 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?

A create tool with six parameters, low schema coverage, and no output schema needs more: where the QR is stored (folderId/companyId interplay), what templateId must reference, and what the call returns are all unaddressed. Only the payload override is covered.

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 only 17% (companyId is the lone documented property), so the description must compensate, yet it only clarifies the payload override semantics. templateId, label, designId, and folderId remain unexplained in both places.

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 QR code') and adds the 'from a template' qualifier, which distinguishes it from siblings like qrs_create and qrs_create_url. It does not name those siblings, so differentiation is implied rather than explicit.

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 usage (use this when a template supplies the type and defaults) but never states when to choose it over qrs_create, qrs_create_url, or qrs_bulk_create, nor any preconditions such as template existence or permissions. Usage is inferable but not guided.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the code is *dynamic*, and the target 'can be changed later without reprinting' — a mutable-vs-static distinction an agent would not otherwise know. It still says nothing about auth requirements, quotas, or the folder plan feature.

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, zero filler, and the core value proposition (mutable redirect) is front-loaded right after the verb. Nothing to trim.

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 no output schema, the description never indicates what is returned (an id? an image URL?) and does not mention the required `label` field or that folderId depends on plan. Annotations cover the safety dimension, so the remaining gaps are moderate rather than severe.

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 60%: designId, folderId and companyId are described in the schema, while label and targetUrl are not. The description supplies real meaning for targetUrl (it is the redirect destination, mutable after creation), but label — a required parameter — and the plan-gated nature of folderId get no added explanation. Marginal value over the schema, so 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?

The description gives a specific verb and resource ('create a dynamic QR code that redirects to `targetUrl`') and the word 'Shortcut:' signals it is a streamlined variant of the generic qrs_create / qrs_create_from_template siblings. It stops short of naming which sibling to prefer, so it is clear but not fully differentiated.

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 phrase 'Shortcut:' plus 'dynamic QR code' implies the appropriate use case (a URL redirect code whose destination may change), but there is no explicit when-to-use statement, no exclusions, and no named alternative among the many sibling tools. Usage 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the downstream consequence that already-printed copies stop working, telling the agent this is a materially destructive act. It still omits reversibility/permanence and any auth requirements, so not 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, front-loading the action and then the consequence. Optimal size for a one-parameter 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 simple delete with one parameter, no output schema, and annotations carrying the safety profile, the description is close to complete: what it does plus the key user-facing consequence. The unaddressed 'id' semantics keep it from being fully sufficient.

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 required 'id' parameter has 0% schema description coverage, so the schema does not explain it and the description never mentions it either. The agent is left to guess what identifier is expected (QR code UUID vs short code) and where to obtain it. The description fails to compensate for the coverage gap.

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

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

States a specific verb ('Delete') and resource ('QR code'), immediately distinguishing it from sibling qrs_create, qrs_update, and the deletes for other resources (designs_delete, templates_delete). An agent can identify the correct tool from the phrase alone.

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

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

Usage is implied by the verb and resource, but there is no explicit when-to-use/when-not guidance, no mention of how this differs from destructive siblings, and no prerequisite information. It is adequate for such a simple, obvious operation but adds no routing help.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds little beyond that, though noting 'all-time scans' signals the returned aggregate is not time-filtered.

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 filler; the resource and the returned facets are stated immediately.

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 enumerates the returned fields, and annotations carry the read-only safety semantics. Minor gaps remain around error behavior for an unknown id, but nothing essential for invoking it 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 0% schema description coverage, so the schema gives only a bare uuid type. The description implies single-item lookup by identifier but never states the id format or where to obtain it, leaving a small gap the schema does not fill.

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 ('Read one') plus resource ('QR code') with an enumeration of the returned facets (content, design, folder, status, short link, all-time scans). It is clearly distinguished from the plural qrs_list by the word 'one', though it does not name siblings 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: fetching a single QR by identifier, versus qrs_list for enumeration or qrs_update for changes. There is no explicit statement of when to use this rather than qrs_list or qrs_get_image, and no 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real context the annotations do not: the output is a rendered image plus the encoded link, and PNG is the default format when none is given. It omits how the image is delivered (inline vs. URL) and any auth/rate-limit notes.

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 tight sentence pair with zero filler, front-loaded with the action and resource before the format/size qualifiers and the return behavior. 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?

With no output schema, the description usefully states what comes back ('shows the image and returns the encoded link'), which is the key missing structured field for a render tool. It stops short of clarifying the image payload form (base64, content block, or URL), a minor remaining 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 coverage is only 33% (only 'size' is described), so the description must compensate and it partially does: it supplies the missing default ('PNG (default)') that the enum lacks. The 64-4096 range duplicates the schema's minimum/maximum rather than adding meaning, and the required 'id' parameter is undocumented in both places.

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: 'Render a saved QR code with its design' tells the agent this returns an image artifact, and 'saved' implicitly separates it from qr_render_preview and qrs_get. However, neither sibling is named, so the agent must infer the boundary rather than being told it.

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 to obtain the image of an existing QR code by id.' There is no explicit when-to-use versus qr_render_preview or qrs_get, no note that the QR code must already exist, and no exclusion guidance, leaving the selection between the three render/get siblings 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=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely non-redundant behavior: sort order, that each row carries a short link and all-time scan count, and the pagination contract (cursor from previous `next`, default 50, max 200).

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 what is returned, then the available filters, then pagination mechanics. Every clause is load-bearing and no filler is present.

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

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

For a read-only list tool with annotations covering safety, the description covers return contents, ordering, filters and pagination well enough to invoke correctly. It stops short of noting result-shape details such as total counts, but that is a minor gap given no output schema exists.

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 schema coverage at 43%, the description carries real weight: it explains cursor usage ("pass `cursor` from the previous `next`"), the default/max limit, the "root" folder sentinel, and label-search semantics. It still just names status/type without explaining their effect on results, so it adds meaning without being exhaustive.

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 ("List QR codes") and enriches it with ordering ("newest first") and the fields returned ("short link and all-time scans"). It does not explicitly name or contrast a sibling like qrs_get or analytics_get, but the name and scope 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 filter list (search, folder, company, status, type) implies the use cases, but there is no explicit "use this when / use X instead" guidance. Nothing routes the agent between qrs_list, qrs_get, and scans_list, so context is only implicit.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely non-obvious behavior: the printed code is unchanged and the change propagates immediately, plus payload is validated against the QR's type. It does not state whether omitted fields are left untouched or cleared, which is the main remaining gap for a partial-update 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 mutation scope and ending with the key invariant about the printed code. Dense but readable; the parenthetical field list is long yet each item earns its place as a discoverability cue.

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 9-parameter tool with nested objects and no output schema, the description covers the mutable surface, payload validation, and the printed-code invariant, while annotations handle safety. Missing is partial-update semantics (unset fields) and any permission/plan caveats, which the agent would have to mine from the 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 78%, so the schema already carries most parameter meaning (access sub-fields, tracking, folderId plan gating, targetUrl shorthand). The description restates the field groups without adding format or constraint detail 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?

Opens with a specific verb+resource ('Change a QR code's...') and enumerates the mutable surface: label, status, payload, target URL, design, folder, access controls. An agent immediately knows this mutates an existing QR rather than creating one, but no sibling (qrs_get, qrs_bulk_create, qrs_create) is named to sharpen 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as qrs_get for reading or qrs_bulk_create for batch work. The only usage signal is the implicit requirement of an existing QR (the required 'id'), which the agent could infer 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the returned data fields, but it does not mention authentication needs, pagination, or rate limits.

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?

Single sentence, front-loaded with the resource and followed by the relevant fields in parentheses. No redundant or filler 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 zero-parameter read-only tool with no output schema, the description supplies the key return fields and is sufficient to call correctly. It could mention whether the workspace list is paginated or empty-state behavior, but those are minor omissions.

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 are zero input parameters, and the empty schema is fully represented. The description does not need to compensate for parameter documentation, so the baseline for a no-parameter tool 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 identifies the exact resource returned (referral share link and signed-up workspaces with date, plan, commission state), making the tool's output purpose clear even without an explicit verb. The title supplies 'Get', and no sibling tool covers referrals, so an agent can identify it.

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 when-to-use guidance, prerequisites, or mention of alternatives is provided; it only describes returned content. An agent must infer that this is the tool for viewing referral programme data, with no explicit routing against other getter 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 establish this as a safe, non-destructive read, so the description's added value is the ordering (newest first), cursor-based pagination, default people-only behavior, and the Free-plan error contract with its upgrade link. That is meaningful operational context beyond the annotations, though it doesn't state rate limits or exact page sizes.

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 what is returned and the ordering, then pagination, then the plan constraint. No filler; each clause carries information, though the returned-field enumeration is slightly list-like prose.

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 enumerates the returned fields (time, country, city, OS, device, referrer, unique), states ordering and pagination, and flags the plan-gated failure mode. A few gaps remain — no page-size or date-window semantics tied to days/limit — but for a read-only list tool this is close to complete.

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 only 17% — only includeBots is documented in the schema, and even its default (people only) is echoed by the description. The description partially compensates: 'cursor-paginated' explains cursor and it names workspace/company/QR scoping, which maps to companyId/qrId. But days, limit bounds, and cursor format carry no meaning from either source, so it does not fully close the coverage gap.

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

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

States a specific resource (raw scan events) and scope (workspace, company, or QR), with the notable qualifier 'raw' that implicitly separates it from an aggregated analytics tool. It is clear what the tool returns, though it does not name its closest sibling (analytics_get) explicitly, so sibling differentiation is only implied.

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

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

The description gives a real availability condition — plans without scan insights (Free) get an upgrade_required error with an upgrade link — which is useful routing context. However, it never says when to choose this over analytics_get or how to combine the workspace/company/QR scopes; 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the client secret is never returned, the callback URLs needed at the IdP are included, and the result is null when SSO is unconfigured. That is real added context for a read 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?

One tight sentence, front-loaded with the resource and scope, with the security caveat and null behavior appended in a compact parenthetical/clause. No wasted words and nothing an agent needs is 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?

There is no output schema, so the description carries the burden of describing returns, and it does: callback URLs, no client secret, null when unconfigured. A brief note on whether other credentials/endpoints are returned would make it fully complete, but nothing essential is missing for a zero-param getter.

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 is 4. Schema coverage is 100% with an empty properties object, so no compensating description is required.

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: 'Show the workspace's OpenID Connect single sign-on settings.' The scope is clear and the mention of callback URLs further pins down what is returned. It does not differentiate from the sibling sso_test (or workspace_get), so it falls 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?

There is no statement of when to call this versus sso_test or workspace_get, and no prerequisites or preconditions. 'Null when none is set up' describes a return state, not usage guidance. An agent must infer the call site 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real context by explaining the outbound call to the IdP discovery document and that it relies on stored settings (which explains the zero-parameter design), but it says nothing about failure modes, timeout behavior, whether a result is persisted, 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?

A single sentence that front-loads the action and ends on the outcome. 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?

With no parameters and no output schema, the description carries the return-value burden and does sketch it ('report whether it answers'), though it does not say whether the report is a boolean, a status code, or an error detail. For a zero-input read-only probe, this is close to complete.

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 the baseline is 4. The description usefully accounts for that absence by noting the settings are stored, so an agent does not hunt for an input it must supply.

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), specific resource (the identity provider's discovery document), and a stated outcome (report whether it answers). It is clearly distinguishable from sso_get by virtue of being a live probe rather than a config read, though the description never names that sibling to make the contrast explicit.

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 rather than stated: the mention of 'the stored settings' signals this is run against an already-configured SSO setup, so it fits a verify-after-configuring flow. There is no explicit when-to-use, when-not-to-use, or reference to sso_get as the alternative.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond 'reusable' – no note on scope/permission requirements, whether payloadDefaults are inherited by derived QRs, or tenant-vs-company visibility implications. With annotations present the bar is lower, but the description still contributes almost no extra behavioral 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?

A single front-loaded sentence with zero filler; nothing is redundant. Its brevity is clean, though it is arguably too terse for a six-parameter mutation, which pushes it just below 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?

For a mutation tool with no output schema, 33% schema coverage, a nested free-form payloadDefaults object, and four sibling template tools, the description leaves too much unexplained – no return behavior, no scope/permission context, no linkage to the template-consuming tools. It is inadequate for the tool's complexity.

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 only 33% – scope and qrType are documented, but designId, description, and the nested payloadDefaults object are undocumented in both schema and description. The description mentions no parameters at all and therefore does nothing to compensate for the coverage gap, which matters most for the opaque payloadDefaults object.

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 (create + template) and adds the meaningful qualifier 'reusable,' so the agent knows this produces a stored, reusable asset rather than a one-off render. It does not distinguish itself from templates_update/templates_get/templates_list beyond the verb, but the name/verb pairing makes the intent 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives. The agent gets no hint that qrs_create_from_template is the consumer of what this tool produces, or when to prefer creating a template over qrs_create directly.

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, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context not in the annotations: 'QR codes already made from it keep working', clarifying the non-cascading impact on related resources. It omits irreversibility and permission requirements, so not 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 terse sentences with zero waste; the core action is front-loaded and the side-effect clarification follows naturally. Every sentence earns its place.

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

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

For a single-parameter destructive delete with full annotation coverage and no output schema, the description is nearly sufficient: it names the resource and the non-cascading effect. It could still note that template deletion itself is irreversible or what permission is needed, so it is not fully complete.

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 one parameter (id) with 0% schema description coverage, so the description would need to compensate. 'Delete a QR template' implicitly identifies the id as a template identifier, which is minimal but consistent with the schema's uuid format. It adds no syntax or format detail beyond that inference.

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 ('Delete a QR template'), making the operation unambiguous and distinguishable from sibling qrs_delete by naming the 'QR template' entity. It does not explicitly name an alternative sibling, so it falls just short of the top mark.

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 says what the tool does but gives no when-to-use/when-not guidance and names no alternative (e.g., qrs_delete for individual codes, or templates_update if removal is the wrong intent). Usage is only implied by the verb.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond the word 'Read' — no note on error behavior for missing IDs, permissions, or what a returned template contains.

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 short, front-loaded sentence with no filler, which is structurally clean. However, the brevity reflects under-specification rather than disciplined conciseness — there is no content to trim because none was provided.

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?

No output schema exists, so the description is the only place to explain what a fetched template returns; it does not. For a lookup tool with an undocumented required parameter, the definition leaves the agent guessing on both input and output.

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

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

Schema description coverage is 0% for the single required 'id' parameter (uuid). The description never mentions the identifier, its format, or where to obtain it, so it fails to compensate for the schema gap.

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

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

States a specific verb (Read) and resource (QR template) with singular scope, which implicitly separates it from templates_list and templates_update. It does not explicitly name a sibling or contrast behavior, so it falls 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 when-to-use guidance, no prerequisites, and no mention of alternatives such as templates_list (to enumerate) or templates_get vs qrs_get. The agent must infer usage entirely from the name.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful scope information (shared workspace templates plus company-owned templates), which is context the annotations don't convey. It says nothing about pagination, ordering, or result shape, so it stays at an adequate 3.

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, no filler, and the scope qualifier is front-loaded immediately after the verb. Nothing in it 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?

For a simple read-only list tool with full schema coverage and annotations covering safety, the description is close to sufficient. The only mild gap is that there is no output schema, so an agent gets no hint about the shape of returned templates, though this is minor for a list endpoint.

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 qrType parameter is fully enumerated with a description, so the schema carries the load. The description never mentions qrType or its filtering effect, so it adds nothing beyond the structured data — 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 ('List QR templates') and adds scope ('shared workspace templates plus your company's own'), which tells an agent what the result set contains. It does not explicitly differentiate itself from sibling templates_get, but the plural list verb makes the distinction inferable.

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 call this versus templates_get or templates_create, and no mention of how the qrType filter affects results. 'you can use' hints at the intent but stops short of any explicit when-to-use or exclusion.

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 openWorldHint=false, so the agent knows this is a bounded mutation. The description adds nothing beyond that: it does not say whether the update is partial or full replacement (i.e., whether omitted fields are cleared), what permissions are required, or what the response contains.

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 five-word fragment, so there is no verbosity problem, but this is under-specification rather than conciseness. No information is front-loaded because no information exists.

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 mutation tool with five parameters, a nested object, zero schema coverage and no output schema requires the description to carry substantial weight. It conveys nothing an agent needs to invoke the tool correctly.

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

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

Schema description coverage is 0% for five parameters, including a nested free-form payloadDefaults object, and the description supplies no information about any of them. Nothing tells the agent what name, designId, description or payloadDefaults accept or how they interact with the required id.

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 "Change a QR template" is essentially a paraphrase of the title "Update template" — it restates the same verb+resource without saying what about the template changes. It does distinguish the mutation from templates_get/list/create/delete by implying modification, but adds no specificity beyond the name.

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 when-to-use guidance, no statement of prerequisites, and no reference to alternatives such as templates_create or templates_delete. An agent must infer the use case entirely from the verb.

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