Yellowhead Digital agent door

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

Goes well beyond the annotations by describing the default hold-and-approve flow, returning {status: 'pending_approval', approval_id}, and the exception requiring a signing-key-proving connection. It also discloses duplicate behavior ('the same comment sent twice is posted twice'), consistent with idempotentHint=false, and confirms append-only 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, followed by availability, default behavior, and constraints in a logical order. The sentences are dense but nearly all carry needed information; some phrasing ('on any plan', the long signing-key clause) is heavier than necessary.

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, the description supplies the missing pieces: the return payload, the approval lifecycle, the follow-up tool, and the idempotency caveat. An agent has everything needed to call it and to explain the result to a user.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema with format, length, and content guidance. The description adds only loose semantics about what the comment text should contain, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Requests a comment on one action item's timeline') and scopes the content type with concrete examples (what was done, what was found, what is needed). It is clearly separable from siblings like update_action_item and list_action_items, and the later line 'this cannot edit or delete anything or change the item's status' reinforces 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?

Explicitly states the permitting condition (only a connection an account admin set up and allowed) and the exclusion (a connection made through an assistant's sign-in cannot, on any plan). It also names get_approval_status as the tool to use for the approval outcome, leaving little 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real context beyond them: no sign-in is required, an account is needed to actually run a Diagnostic, and the optional inputs are inert ("nothing is scanned, stored or looked up"). It stops short of describing response shape or size, which keeps it off a 5.

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

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

The key facts (what it is, no sign-in, scope of content, fit conditions, inert params) are front-loaded and every clause carries information. The middle semicolon-chained inventory of plan/scan content is dense and reads as a run-on, which costs a point on structure but not on usefulness.

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-required-parameter, read-only, closed-world info tool with no output schema, the description supplies everything needed: the subject matter, the returned categories, the no-auth condition, and the side-effect-free nature of the inputs. Nothing an agent needs in order to decide to call it or to pass values correctly is missing.

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

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

Schema coverage is 100% and both parameters are documented as prefill values, so the baseline would be 3. The description adds meaning beyond the schema by asserting the values are never validated, fetched or persisted — a behavioral constraint on the parameters that an agent would otherwise assume away when passing a URL.

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

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

The description opens with a specific verb+resource ("Describes Yellowhead Digital") and enumerates exactly what content is returned: the ten check areas, plan prices, monthly Diagnostic counts, paid scans, and a prefill link. It is cleanly separable from siblings such as get_diagnostic, list_diagnostics and run_diagnostic because it explicitly frames itself as pre-account, informational, and non-executing ("nothing is scanned, stored or looked up").

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

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

It gives explicit triggering conditions: "Fits questions about what Yellowhead does or costs, whether it checks something, or how to get started, including before any account exists." That is clear context for when to call it, though it never names a sibling to prefer instead (e.g. run_diagnostic for an actual scan) beyond the implicit "nothing is scanned" contrast.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description adds real substance beyond that with the null-before-completion rule, the results_unavailable fallback when stored results cannot be read, and the caveat that absent failing checks do not imply WCAG conformance. It stops short of describing permissions or any partial-failure behavior beyond the one fallback flag.

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

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

The content is front-loaded with the primary return shape, but it is delivered as one dense, run-on enumeration that mixes entity fields, result structure, edge cases, and methodological caveats. Every element is relevant, yet the lack of sentence breaks or ordering makes it harder to scan than it needs to be.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: entity fields, run summary, per-template roll-up with its caps, re-scan fix verification, and the null/unavailable states. The only meaningful gap is how to obtain the required id.

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 sole parameter is documented only as "by id", with no indication of the uuid format or where the id is obtained (presumably list_accessibility_scans). The description does not compensate for the coverage gap, so an agent must infer the id source.

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 ("Returns one Accessibility Scan by id") and immediately distinguishes itself from the list sibling by emphasizing a single scan retrieved by id. An agent can tell this apart from list_accessibility_scans without opening the schema.

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

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

Usage is only implied: "by id" suggests it is a follow-up to listing scans, but the description never names list_accessibility_scans as the source of ids or states when to prefer this over it. No exclusions or prerequisites 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond them by explaining the domain semantics: fixes occur on the business's own systems, verification only happens when a later Diagnostic observes the fix externally, and Assist can take on work in-house — context an agent needs to interpret the returned status correctly.

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 first sentence is well front-loaded and information-dense. The trailing sentences on remediation ownership, external verification, and the Assist service are interpretive context, but the final sentence about Assist reads as promotional rather than helping an agent decide to call this 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 single-item read with rich annotations and one simple parameter, the definition covers what is returned and how to think about status/verification, which is most of what an agent needs. It lacks an output schema, so nothing documents error behavior for an unknown id, but the enumeration of returned fields largely compensates.

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 required parameter with 0% schema description coverage; the only semantic the description supplies is that the item is retrieved "by id," and it never states that the id must be a UUID or where such an id comes from (presumably list_action_items). Minimal compensation 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 ("Returns one action item by id") and immediately enumerates the detail it carries: rationale, description, remediation guidance, tools involved, status, dates, and source Diagnostic. The singular "one ... by id" cleanly separates it from list_action_items without needing to name the sibling.

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?

"Fits explaining or planning one fix" gives implied usage context, but there are no explicit when-not conditions and no named alternatives (list_action_items for enumeration, update_action_item for mutation, add_action_item_comment for discussion). An agent must infer the routing itself.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior. The description adds real context beyond them: the full set of possible states, that an account admin in the Yellowhead app performs approval, and that only requests made through this connection are visible — a meaningful scoping limitation.

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?

Dense but front-loaded: the purpose, the state list, and the visibility scoping each earn their place. The single long sentence is a bit run-on, which slightly hurts scanability.

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 names the returned fields (state, request and decision times, reason). It could go further by noting what to do when a state is still pending_approval or applying, but it is otherwise sufficient for a one-parameter read tool.

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

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

Schema coverage is 0%, so the description carries the parameter burden. It explains where approval_id originates (the three sibling tools) and that it keys a held request, which the bare uuid-format schema does not convey; it doesn't describe format or error behavior for an unknown 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 and resource ('Returns the state of a held request by its approval_id') and enumerates the exact state values, which distinguishes it clearly from siblings like get_run_status or get_diagnostic.

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

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

It routes the agent by naming the three sibling tools whose output yields an approval_id (update_action_item, add_action_item_comment, run_diagnostic), which is strong when-to-use guidance. It stops short of stating when to poll versus when to stop or what to do on terminal states, so it doesn't reach 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 establish readOnly, idempotent, non-destructive and closed-world, and the description still adds substantial context beyond them: the results-null-until-complete lifecycle state, the results_unavailable fallback when stored results cannot be read, and a note that the unread data lives in the Yellowhead app. It even flags an interpretive caveat — citations vary between runs and are not on their own evidence of why a site was or was not cited — which no annotation could convey.

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

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

The purpose is correctly front-loaded in the opening clause, but the remainder is one long chain of clauses enumerating return fields, which is hard to parse and would be better as a short list. The 'in the Yellowhead app' disclaimer about cited page addresses is repeated in spirit at the end after already being covered by the results_unavailable sentence, so some wording does not earn 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 full burden of describing return values, and it does so thoroughly — including the null/unavailable edge states and the head-to-head competitor questions. What is missing for a single-parameter lookup of this complexity is only the provenance of the id and any note on result size or auth, which are minor relative to what 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?

There is a single required parameter whose schema has zero description coverage, so the description must carry the meaning. It says 'by id' and consistently frames the scan as an identified object, but it never states the id is a UUID or where the caller obtains one, which leaves a real gap for a 0%-coverage schema. It beats a bare baseline because the surrounding text makes the identity relationship unambiguous, but it does not fully compensate.

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

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

The first clause names a specific verb and resource with scope: 'Returns one Citation Scan by id,' which immediately separates it from the list_citation_scans sibling. The rest of the description enumerates exactly what the returned object contains (website, category, country, status, dates, competitor_domains, results, head-to-head questions), so an agent knows what it is fetching before opening any schema.

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

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

Usage is only implied: the tool fetches a single scan by id, so an agent infers it should call list_citation_scans first to obtain an id, but the description never says this or names that alternative. There is one useful conditional hint — 'results is null until the scan completes' implies you should not call it expecting results on a running scan — but there are no explicit when-to-use or when-not rules.

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

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

Goes well beyond the readOnly/idempotent annotations: results is null until the scan completes, results_unavailable signals an unreadable stored result set, an unreadable robots.txt is reported as unknown rather than absent, and lists are capped at 25 entries with totals supplied. These are exactly the edge cases an agent needs to interpret a response correctly.

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

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

The core purpose is front-loaded, but the body is one long run-on sentence with heavy nested parentheticals that is hard to scan. The 'in the Yellowhead app' caveat is stated twice, once for results_unavailable and once for per-URL results, which is redundant.

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

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

No output schema exists, so the description carries the full burden of explaining return values, and it does so comprehensively: scan metadata, page counts by category, run summary contents, null semantics, and failure flags. Nothing material is missing for an agent to call and interpret this tool.

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

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

There is one parameter with 0% schema description coverage, so the schema contributes nothing beyond the uuid format. The description says 'by id' and thus implies the id identifies a specific scan, but it does not say where to obtain that id (presumably list_crawlability_scans), leaving the parameter only partially explained.

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: 'Returns one Crawlability Scan by id'. The singular 'one ... by id' scope cleanly distinguishes it from the sibling list_crawlability_scans and from the other get_* scan tools, which cover different scan types.

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

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

The 'by id' framing implies this is the single-record lookup and the list tool is the way to enumerate, but the description never states when to use this versus list_crawlability_scans or what to do if the id is unknown. 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new state information the annotations cannot: report_id appears only once the diagnostic has completed, which tells the agent how to detect an incomplete run.

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 return shape and followed by the usage condition. Every clause carries information: the field list, the completion-dependent report_id, and the hand-off to get_report.

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 correctly takes on the job of describing the return payload, including the conditional report_id. The only gap for a simple one-parameter lookup is behavior when the id is unknown (error vs. empty result) or whether it can be polled repeatedly while a run is in progress.

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, so the schema names it but says nothing about what it identifies. The description compensates only partially by framing the call as "one Diagnostic by id," implying it is the diagnostic identifier, but it never states the UUID format or where such an id comes from (e.g., list_diagnostics or run_diagnostic).

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?

"Returns one Diagnostic by id" is a specific verb plus resource, and the description then enumerates the payload (status, business name, website, client_id, MIDAS score, created date, report_id) so an agent knows exactly what it gets. It also explicitly separates this from get_report, which returns the findings.

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?

"Fits checking whether a particular run has finished; the findings themselves come from get_report" gives a clear use case and routes the agent to the right sibling for report content. It does not, however, distinguish this from the closely related get_run_status or explain when to use list_diagnostics instead of fetching one by id.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral fact beyond that: only 'published' audits are returned, implying drafts or unpublished records are not accessible. It does not say what happens for a missing or unpublished id.

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 the core behavior front-loaded. 'As published to the account' partially repeats 'published', a minor redundancy, but nothing is padded or buried.

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

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

A simple single-parameter read tool with rich annotations, so the burden is light. However, with no output schema the description should hint at the returned shape (findings, recommendations, metadata), and it instead gestures at findings without describing them.

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

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

With a single required parameter and 0% schema description coverage, the schema documents only 'uuid' format. The description clarifies that the id selects a published audit, which adds a little meaning, but gives no guidance on where such ids come from (presumably list_infrastructure_audits).

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: returns one published Infrastructure Audit by id, scoped to the account. The sibling list_infrastructure_audits is not named, so the single-vs-list distinction is left for the agent to infer.

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 only usage signal is the vague phrase 'Fits working from its findings and recommendations', which describes a scenario rather than a selection rule. It never says when to use this instead of list_infrastructure_audits or get_strategic_assessment, nor what to do when the id is unknown.

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 read-only/idempotent/non-destructive; the description goes far beyond them by disclosing the noise threshold that suppresses small moves, that null report fields mean a pair could not be confirmed in the account, that competitor/research/prospect Diagnostics are excluded from open-item counts, and that archived workspaces and out-of-plan accounts are omitted. The empty-list and truncated caveats ('not that nothing changed', 'the list may be incomplete') are exactly the failure modes an agent would otherwise misreport.

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 purpose and ordering, and dense with substantive detail. It is a single long block paragraph that repeats the threshold idea twice ('more than the usual run-to-run variation' and later 'more than that in the window'), which costs some readability on a description this long.

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 and does so fully: item fields (client_id, name, previous/current MIDAS, change, both report_ids with dates, critical/high open items), pagination signaling via truncated plus cursor, and plan eligibility. Nothing material is missing for correct invocation or 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'since' is tied to the client's most recent scored Diagnostic rather than being a raw filter, and 'direction' is described as narrowing to declines or improvements. limit and cursor are left to the schema, which is acceptable given their self-explanatory descriptions.

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

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

Opens with a specific verb and resource ('Lists the client workspaces whose MIDAS score moved since a date'), plus ordering ('largest move first'). This clearly separates it from list_portfolio (roster) and from list_diagnostics/get_diagnostic (single-report retrieval).

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

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

Gives concrete use cases ('which of my clients got worse this month', 'who improved since our last review') and explains how direction and client_id narrow results. It never explicitly names list_portfolio as the alternative for a plain roster, so routing is inferred 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?

Goes well past the readOnly/idempotent annotations: it documents plan-dependent output variation detailed down to individual fields (Free, Starter, Pro thresholds), the exclusion of internal signals, the report_not_ready failure mode, and score variance between runs. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the return contents, which is good, but the plan-gating information is delivered as one very long sentence with stacked clauses that is hard to parse. The information earns its place, yet the structure could be split into shorter, scannable statements.

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 must describe the return value, and it does so field-by-field, plus adds the not-ready case and the caveat on run-to-run score movement. An agent has everything needed to call this and interpret the result correctly.

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

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

The schema has one parameter with 0% description coverage, so the description bears the burden. It only says 'by id' and never clarifies that this is the Diagnostic id (e.g. from list_diagnostics) or what happens with a stale or foreign id, adding little meaning beyond the uuid-typed schema field.

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 ('Returns the report of a completed Diagnostic by id') and enumerates the returned contents (side_a_scores, side_b_scores, MIDAS score, executive summary, blind spots, etc.). It does not differentiate itself from siblings like get_diagnostic or get_run_status, which is a notable gap given the crowded sibling list.

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 conditions: only for a 'completed' Diagnostic, with report_not_ready returned otherwise, and names the usual next step (a Strategic Assessment via get_strategic_assessment) when business context or trade-offs are needed. It stops short of explicitly stating when to prefer get_diagnostic over this tool.

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

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

Beyond the readOnly/idempotent annotations, it discloses the slow-flag threshold behavior, the 30-minute fail boundary, that a longer-than-expected run is reported as running rather than failed, and that a failed result indicates whether a retry consumes another monthly Diagnostic. These are non-obvious operational semantics an agent could not infer from the schema or annotations.

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

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

Front-loaded with the status enumeration and only then the timing thresholds; every sentence carries information. The retry/credit sentence is somewhat convoluted in phrasing, which keeps it just short of 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?

With no output schema, the description carries the return-value burden itself and does so: it names the status field, start time, elapsed minutes, the slow flag, and the failure explanation. For a one-parameter polling tool this is 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 0% and the single parameter is undocumented in the schema, but the description compensates by explaining that diagnostic_id is the id supplied by start_diagnostic and list_diagnostics. It does not restate the uuid format, but the provenance guidance is the more useful half.

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 and enumerates the exact status values it reports (queued, running, completed, failed) keyed by diagnostic_id. It does not explicitly contrast with the sibling get_diagnostic, so an agent must infer that this is the lightweight polling view rather than the full-result view.

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 closing line '"is it ready yet?" at any point in the conversation' gives a concrete usage trigger and reinforces that repeated polling is acceptable. It also supplies timing expectations (5-10 minutes typical) that shape when calling is useful, but gives no explicit when-not guidance or rate-limit advice.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds one genuinely useful constraint — that only *published* assessments are retrievable — but says nothing about behavior for unknown/unpublished ids or whether any auth/scope applies.

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 verb and scope, with no wasted text. The second sentence ("Fits working from its priorities and recommendations") is awkwardly phrased and slightly cryptic, which costs a point.

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 simple single-parameter read tool with complete annotations, so the bar is modest. However, with no output schema the description should at least sketch what an assessment contains or note not-found behavior; instead it only gestures at "priorities and recommendations."

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

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

There is a single required parameter with 0% schema description coverage; the schema only supplies type string and format uuid. The description adds the meaning "identifies one published assessment" but no format, source, or error semantics for an invalid id, so it only marginally compensates 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 gives a specific verb and resource ("Returns one published Strategic Assessment by id") and clarifies what the resource actually is ("the deliverable written for the business after its live session"). The singular "one ... by id" implicitly separates it from list_strategic_assessments, though that sibling is never named.

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

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

"Fits working from its priorities and recommendations" hints at the downstream use case but never states when to call this versus list_strategic_assessments or how to obtain the required id. 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 read-only, idempotent, non-destructive, closed-world access, so the description focuses on what the agent cannot get elsewhere: the exact returned fields (used, limit, remaining, plan, pool, resets_on), the Free-plan first-month note, and the extra per_client value when client_id is supplied. With no output schema present, this enumeration is exactly the behavioral disclosure an agent needs.

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

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

Front-loads the core return fields, then adds the Free-plan caveat, then the client_id behavior, then the use case. The first sentence is long and parenthetical-heavy, and the usage guidance would be stronger placed earlier, but every clause carries information and none 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 single-optional-parameter read tool with no output schema, the description covers return shape, plan-conditional behavior, per-client behavior, and intended questions. Only minor gaps remain, such as the date format of resets_on and what a 'pool' value looks like.

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% for the single optional client_id, but the description compensates by explaining its semantic effect: the response gains that workspace's own monthly limit under per_client. It does not explain defaults when client_id is omitted (implied) or what happens with an unknown id, so it adds real meaning but not a complete picture.

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 ('Returns') and a precise resource ('this month's Diagnostic allowance'), and the topic (quota/usage) is distinct from every sibling, which deal with scans, reports, or action items rather than allowance accounting. An agent can tell this apart from get_diagnostic and list_diagnostics without opening any schema.

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

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

The closing sentence gives explicit use-case framing ('how many Diagnostics are left this month and when the allowance resets'), which maps cleanly onto user question phrasing. It stops short of naming an alternative tool or stating when not to call it, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so safety needs no restating. The description adds genuinely non-structured behavior: results are ordered newest first, status values are explained (including that the first three are the free sitemap import/review stages), sample_mode distinguishes a re-scan from a first scan, and an empty page is explicitly not evidence that no scans exist. Only pagination/limit behavior is left to the schema.

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

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

Purpose and ordering are front-loaded, which is correct, but the third sentence is a single sprawling enumeration of nine return fields with parenthetical status definitions that is hard to scan. Given there is no output schema the enumeration earns its place, but it could have been structured as a list rather than one run-on sentence.

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

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

With no output schema, the description carries the full burden of describing return shape and it does so, field by field, including counts, template count, ids and dates. Status semantics and the empty-page caveat close the remaining interpretive gaps for a four-parameter list tool.

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

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

Schema coverage is 50%: limit and cursor are documented in the schema, while status and client_id are bare. The description compensates well for status by listing all nine lifecycle values and their meanings, and labels client_id as a filter. It adds no meaning for client_id beyond being a filter, which keeps it from a 5.

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

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

The opening sentence gives a specific verb and resource ("Lists the Accessibility Scans") plus scope ("in the connected account") and ordering ("newest first"). The resource is distinct from every sibling (list_citation_scans, list_crawlability_scans, list_diagnostics), and a second sentence defines what an Accessibility Scan actually is, so the agent knows what records it will get.

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 names the two filters (client_id and status) and explains how to interpret an empty result, which is real context for calling the tool. It never contrasts this with get_accessibility_scan or get_run_status, so the choice between listing and fetching a single scan is left to inference from the names.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real value by defining the status lifecycle semantics — notably that completed is self-reported, confirmed is a second-party sign-off, and verified comes from a later Diagnostic observing the fix externally. It also explains that an empty page means nothing matched these filters, which prevents the agent from misreading an empty result as an error.

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

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

The description is front-loaded with scope and ordering, then moves to return fields, statuses, filters, and empty-page behavior with almost no filler. The long enumeration of returned fields is dense but justified because no output schema 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?

With no output schema, the description carries the return-value burden and does so by enumerating the item fields, and pagination is handled by the schema's limit and cursor parameters. It is nearly complete, though it omits whether additional pages exist in the response envelope or how to detect the end of a result set beyond the cursor.

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 40%, with status, client_id, and source_id undocumented in the schema, but the description compensates by naming all three as filters and mapping source_id to the originating Diagnostic in the returned-field list. It does not spell out combination semantics or uuid format expectations beyond what the schema's format field 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 first sentence states a specific verb and resource ('Lists the action items'), scopes it to the connected account, and specifies ordering ('newest first'). It is clearly distinguishable from the singular sibling get_action_item, which returns one item rather than a page.

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 closing sentence gives concrete usage contexts ('what should we fix first' and progress reviews), so the agent knows the intended scenarios. It stops short of explicit when-not guidance or naming alternatives such as get_action_item for single-item retrieval, which keeps it below a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: result ordering, the full set of item fields, the status lifecycle values, the 0-to-1 range of target_share, and the meaning of an empty page. Because there is no output schema, this return-shape disclosure is doing real work rather than repeating structured 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 leading sentence front-loads the action, scope, and ordering before the domain explainer, which is the right structure. The rest is dense but nearly every clause carries information; the item-field enumeration is long yet justified by the absence of an output schema. Minor loss for being one undifferentiated block with no visual breaks.

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-required-parameter list tool with no output schema, the description supplies ordering, filter semantics, per-item fields, and an explicit empty-result caveat — covering the main ways an agent could misread this tool. Only small gaps remain, such as total-count behavior or what happens with an invalid filter 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 coverage is 50%: limit and cursor are documented in the schema, while status and client_id are bare enums/UUIDs. The description labels these two as 'Filters' and restates the status values in prose, but adds no semantics the schema lacks — nothing about what a client_id refers to or how status filters interact. 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 ('Lists the Citation Scans'), the scope ('in the connected account'), and the ordering ('newest first'). It goes further by defining what a Citation Scan actually is (fixed buyer questions in one category/country across AI answer engines, recording cited websites), which makes the tool's output intelligible without any external domain knowledge.

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

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

Names the two filters (client_id, status) and explains the empty-page semantics ('none were returned for these filters, not that the account has none'), which is exactly the kind of interpretation guidance that prevents wrong conclusions. It stops short of explicitly routing between this and get_citation_scan or list_diagnostics, so no true when-not guidance is 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile needs no restating. The description adds ordering behavior (newest first), the full item payload shape (id, target_domain, status, sample_mode, page counts, client_id, diagnostic_report_id, dates), and the empty-result semantics, all beyond what annotations provide.

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

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

The core purpose is front-loaded in the first clause and the single paragraph is dense with signal rather than filler. It runs long because it covers the item shape and status vocabulary, which is necessary given there is no output schema, but the field enumeration reads as a run-on list and could be structured more scannably.

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 four optional params, no output schema, and simple read-only semantics, the description supplies exactly what is missing elsewhere: what a scan is, what each returned item contains, what the statuses mean, and how to interpret an empty page. Nothing an agent needs in order to call it correctly and interpret the result 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 coverage is 50%, with limit and cursor already documented in the schema. The description compensates by explaining what each status value means in the domain ('the first three are the free sitemap import and page review'), which directly informs filtering, though client_id is still only named, not explained, and cursor paging is left entirely to the schema.

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

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

The description opens with a specific verb and resource ('Lists the Crawlability Scans in the connected account, newest first') and then defines what a Crawlability Scan actually is, so an agent knows the object being listed. It does not explicitly name the singular sibling get_crawlability_scan as the alternative for a single scan, relying on the plural verb to imply the distinction.

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

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

It states the available filters ('client_id and status') and warns that an empty page means no match for these filters rather than an empty account, which is genuinely useful usage context. However, it never says when to reach for this list versus get_crawlability_scan, list_diagnostics, or the other list_* siblings, and gives no guidance on iterating with 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?

Beyond the annotations, which already declare this as a safe read-only idempotent operation, the description discloses important behavior: ordering, returned fields, status values, the 15-minute timeout-to-failed rule, account-wide visibility, filter semantics, and the caveat that an empty page means no matches for the filters rather than no Diagnostics existing.

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

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

The description is front-loaded with the purpose and packs useful information into a compact paragraph. The long sentence enumerating returned fields and statuses is dense but justified because there is no output schema; overall it avoids 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 list tool with no output schema, the description is highly complete: it explains what is returned, status values, ordering, visibility, filters, pagination edge-case meaning, and example use cases. An agent has enough information to call it correctly without needing more context.

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

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

The input schema covers limit and cursor clearly, but client_id has no schema description; the tool description compensates by explaining it filters to one client workspace. It also reinforces the meaning of since and connects empty pagination results to filter semantics. Limit and cursor behavior are left largely to the schema.

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

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

The description states a specific verb and resource: it lists Diagnostics in the connected Yellowhead account. It adds scope details like newest-first ordering and account-wide visibility, but it does not explicitly distinguish this list tool from the sibling get_diagnostic tool.

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

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

It gives clear usage context through example questions such as 'what Diagnostics do we have' and 'is my Diagnostic ready', and notes that it can help find two runs to compare. However, it does not explicitly say when to use get_diagnostic instead, nor does it state any exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior beyond that: newest-first ordering, the published-only visibility rule, and the set of fields returned, which an agent cannot infer from the schema.

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

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

Three short sentences, front-loaded with the ordering and returned fields, then the visibility rule, then the filters. The sentence 'Only published audits appear: one that is in progress appears once it is published' is slightly redundant, but otherwise 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?

For a four-parameter, no-required-field list tool with no output schema, the description covers scope, ordering, returned fields, visibility, and filters. Pagination behavior beyond the cursor/limit schema fields is not elaborated, which is the only notable omission.

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 50%: limit and cursor are documented in the schema, while client_id and diagnostic_report_id have no descriptions there. The description labels those two as 'Filters', which adds modest meaning but does not explain what a diagnostic_report_id selects relative to client_id, leaving the gap only partly closed.

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

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

The description opens with a specific verb and resource ('Lists the published Infrastructure Audits in the connected account') and lists the fields returned (ids, Diagnostic followed, client_id, dates). It does not explicitly differentiate from the sibling get_infrastructure_audit for a single audit, so it falls just short of a 5.

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

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

Usage is implied: this is the collection lister, refinable by client_id and diagnostic_report_id. The visibility rule ('only published audits appear; in-progress appears once published') is genuinely useful guidance about when results will be absent, but there is no explicit comparison to alternatives such as get_infrastructure_audit or list_diagnostics.

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 read-only, idempotent, non-destructive and closed-world, so the description is free to add real behavioral context — and it does: pagination is one page at a time with a total for 'shown out of how many', the latest Diagnostic may be running or failed, unscored clients sort last, and the two item counts exclude competitor/research/prospect Diagnostics while noting list_action_items still returns them.

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

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

Purpose is front-loaded in the first clause and every sentence carries information, but the body is a single dense run-on covering rows, sorts, filters and plan gating with no visual separation, forcing the agent to parse clauses rather than sections. The sort list duplicates the schema enum verbatim, which costs space without adding meaning.

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

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

No output schema exists, so the description carries the full burden of describing return values and it does so field by field, including the caveat that the Diagnostic may be in-flight or failed and the precise definition of each open-item count. For a nine-parameter, paginated list tool, an agent has everything needed to call it and interpret the response.

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

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

Schema coverage is 100%, so the schema already carries the bulk of parameter meaning; the description still adds value by stating that in the score and date sorts a client with no Diagnostic or score comes last, and that pillar narrows both the critical/high count and min_open_high_priority_items to that area. The sort and pillar additions go slightly beyond the enum text, but most of the rest restates what the schema already says.

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

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

Opens with a specific verb and resource plus the exact scope: 'Lists the client workspaces of the connected team account (brand workspaces on Business Enterprise), one page at a time.' It then enumerates the per-row payload (client_id, name, website, latest Diagnostic, MIDAS score and tier, action-item counts, next Diagnostic), which unambiguously separates it from list_action_items, list_diagnostics and get_portfolio_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?

States concrete fit scenarios ('which clients need attention', ranking clients, finding a client_id by name) and explicitly routes to the downstream tools that consume the result: list_action_items and list_diagnostics. It also states the plan gate (Agency, Business Enterprise, custom) and clarifies that an empty page means no match rather than no workspaces — a real usage trap.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. Beyond that, the description discloses non-obvious behavior the annotations cannot: a default ordering (newest first), a visibility rule that hides booked or in-progress assessments, and the consequence that an empty result set is not evidence of absence. Those are precisely the behavioral traits an agent could otherwise misread.

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 core statement (what is listed, ordering, returned fields), then the visibility caveat, then filters, then a definition. Sentences are dense and mostly earn their place. The closing definition of a Strategic Assessment is helpful for disambiguation but is the one part that could be trimmed if space were 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?

With no output schema, the description correctly compensates by enumerating the returned fields, and it explains the visibility filter that shapes results. Pagination mechanics are left entirely to the schema's limit/cursor descriptions, which is acceptable. It is essentially complete for a filtered list tool; only the semantics of the two id filters remain unstated.

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

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

Schema coverage is 50%: limit and cursor are documented in the schema, while client_id and diagnostic_report_id carry no descriptions there. The description names both filters but adds no semantics beyond the names — no indication of whether client_id scopes results to a single client, or whether diagnostic_report_id returns the assessments derived from one diagnostic. Naming the parameters is a marginal gain over the schema, so baseline 3 is right.

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 ('Lists the published Strategic Assessments in the connected account') plus ordering ('newest first') and the fields returned (ids, Diagnostic, client_id, dates). It also defines the domain object itself, so an agent knows what an assessment is versus a Diagnostic. The only minor gap is that it never names get_strategic_assessment as the single-item counterpart, but the list-vs-get distinction is unambiguous from the wording.

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 context for use: only published assessments appear, and an empty page does not mean none was ordered, which is exactly the kind of caveat that prevents a wrong conclusion. It also names the two available filters. It stops short of explicit routing ('use get_strategic_assessment to fetch one by id', 'use list_diagnostics to see source diagnostics'), so it is clear-but-not-exhaustive rather than a full when/when-not guide.

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

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

Goes well beyond the annotations: every run is held for admin approval regardless of connection settings, returns {status: 'pending_approval', approval_id}, consumes one included monthly Diagnostic before falling back to per-run prepaid billing or outright refusal, and billing mode is re-checked at approval with refusal on drift. Turnaround of 5–10 minutes is disclosed. It does not address what happens to duplicate submissions or how to cancel a pending run, which keeps it off 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?

Front-loaded with the core action and prior_diagnostic_id before the eligibility and billing rules. It is a single dense paragraph of long sentences; the permission and billing clauses are necessary but could be split into shorter statements for faster scanning.

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 7 parameters, nested objects, no output schema and open-world/non-idempotent annotations, the description covers eligibility, mutation limits, billing, approval flow, expected latency and follow-up tools. An agent has everything needed to decide and call 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 coverage is 100%, so a baseline of 3 applies, but the description adds real meaning: omitted side_a_scores and spend fields replay the prior run's values, and the approver sees each change beside the earlier value — a semantic the schema's "merged over the prior run's scores" only partly conveys. The billing note on which fields matter is useful context too.

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 ("Requests a new Diagnostic") plus the scope that separates it from its sibling start_diagnostic: it replays an earlier run's intake via prior_diagnostic_id rather than starting fresh. The immutable dimensions (website, business, account) are 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 layered when-to-use and when-not-to-use conditions: only on an admin-created Yellowhead connection explicitly allowed to make this request, never on an assistant sign-in connection, and only for accounts enabled for assistant-requested runs. It also names the wrong-tool cases indirectly (site/business/account cannot be changed here) and points to get_usage, get_approval_status and get_diagnostic for the surrounding workflow.

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 non-read-only, open-world, non-idempotent, non-destructive, so the safety profile is largely covered. The description still adds substantial value beyond that: nothing is created or charged on the first call, quota_exhausted returns a reset date and plans page, a run takes 5-10 minutes with a completion email, and a repeat start after an incomplete run does not consume another Diagnostic.

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 one dense ~350-word paragraph with no breaks, packing quota behavior, timing, workspace filing, Agency-plan prospect creation, client workspace creation, and connection requirements into undifferentiated prose. The two-call protocol is correctly front-loaded, but several clauses are hard to parse on a single read and would benefit from structure.

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, no-output-schema, multi-phase tool it is unusually complete: it describes exactly what the preview returns, what the token does, what is and isn't created before confirmation, and how progress is checked. The main remaining gap is the unresolved relationship with the sibling run_diagnostic.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, which sets the baseline at 3. The description does add cross-parameter meaning the schema cannot express - earlier_report_id backfilling website, name, ratings and budget, and ratings defaulting to 5 for "not sure" - but the file_as/client_name/prospect_name rules largely restate schema text.

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

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

The description names a specific verb and resource ("Starts a Diagnostic of a website for the signed-in person") and immediately frames the two-call preview/confirm protocol, so the agent knows what the tool does. It does not, however, distinguish itself from the sibling run_diagnostic, leaving ambiguity about which entry point to pick.

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?

Rich conditional guidance: when earlier_report_id should be used (a re-check), when file_as prospect creates a workspace, when client_name is allowed, and what happens when quota is exhausted. What is missing is any explicit statement of when to prefer this over run_diagnostic or how it relates to list_diagnostics/get_run_status beyond the passing mention of progress reporting.

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

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

Goes far beyond the annotations by disclosing the default pending-approval path, the exact result shape {status: 'pending_approval', approval_id}, the admin approval step in the app, and the narrow condition under which changes apply immediately (allowed connection plus signing-key proof per request). It also clarifies domain rules the agent could not infer: suggested/verified/confirmed are not settable here, and completed records work done without verifying it. Consistent with destructiveHint=true and idempotentHint=false.

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

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

Front-loads the purpose, then layers preconditions, approval behavior, and domain rules in a logical order with no filler. It is dense and slightly repetitive around connection eligibility, but each sentence carries operational information an agent needs before invoking.

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 high-stakes mutation tool with no output schema, yet the description supplies the return shape, the approval lifecycle, the fallback lookup path, and the domain constraints on status values. An agent has everything needed to call it correctly and interpret the result.

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

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

With 60% schema coverage, the description adds substantial meaning for status by naming the four settable values and, more importantly, the three values that cannot be set and why. It also clarifies that marking completed does not verify. resolution_notes is only named, with no semantics beyond the schema's maxLength, which is the remaining 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?

Opens with a specific verb and resource — "Requests a change to one action item" — and enumerates exactly which fields can change (status, assignee, due date, resolution notes). It is trivially distinguishable from read siblings like get_action_item and list_action_items, and from add_action_item_comment.

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?

Establishes clear preconditions for use: the connection must be admin-created in the Yellowhead app, and assistant-sign-in connections cannot use it on any plan. It also routes the agent to get_approval_status for the outcome. It stops short of explicitly contrasting with read or comment siblings, but the gating conditions are unambiguous.

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