Ironfang

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

Goes well beyond the annotations (readOnly=false, openWorld=true, idempotent=false, destructive=false) by disclosing the pre-acceptance quota check, refusal semantics with billing code and no audit created, billing counting ('one audit.capture per page captured', failed pages count nothing), and the eventual-consistency detail ('when it finishes'). This is unusually rich and directly actionable 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?

Front-loaded with the action, then behavior, then the polling handoff, with no padding. The middle sentences ('the product admits its page bound against the organisation's usage') are dense and grammatically strained, slightly reducing readability, but 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 quota-gated create tool with no output schema, the description covers preconditions, refusal, billing impact, and follow-up well. It stops short of stating what is returned on success (e.g., an audit identifier), leaning on the poll pointer instead, which is a minor 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 50% (reason is documented in-schema; site_id is not), so the bar is roughly baseline. The description implies single-site scope ('one site') but adds no syntax or constraint detail for site_id or reason beyond what the schema already carries, so it neither compensates nor detracts.

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

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

The first sentence gives a specific verb and resource with scope: 'Start a manual audit of one site now.' It also names the sibling it hands off to ('Poll audit.audit.get for progress'), so an agent can separate creation from progress retrieval 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?

Usage is implied through the operational preconditions (page bound vs. org usage, refusal on exhaustion) and the pointer to audit.audit.get for polling. However, there is no explicit when-to-use/when-not-to-use guidance or comparison against other audit.* creation/listing tools, leaving selection mostly 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine context the annotations cannot: that the result reveals what it counts on audit.capture, that Merkle root and signing key appear only 'once sealed', and that evidence is never returned inline. This state-dependent disclosure is real added value.

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 resource ('One audit: ...'), no filler. It is dense with domain jargon, but each clause carries distinct information about the returned fields.

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 full burden of describing the return shape, and it does so comprehensively for a getter. Minor gaps remain (behavior on a missing or unsealed audit, error semantics), but the essential return contract 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 description coverage is 100% for the single audit_id parameter, which documents its source (audit.audit.list or audit.audit.create). The description adds no parameter-level detail, so the baseline 3 is correct.

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 enumerates exactly what a single audit record contains (state, page counts, compliance result, capture counts, and sealed Merkle root/signing key), which clearly separates it from audit.audit.list (many) and audit.audit.create (write). It lacks an explicit retrieval verb, but the required audit_id in the schema and the 'One audit' framing make the getter purpose unambiguous.

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

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

Usage is implied rather than stated: the reader infers you call this to inspect a single audit, likely after create/list. The note that 'The evidence bundle is a resource, never inline' gives a routing hint away from this tool, but there is no explicit when-to-use or when-to-choose-a-sibling 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 the safe read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's added value is the sort order ('newest first') and the returned content ('status, compliance state, page counts and what each counted on audit.capture'). It does not disclose pagination or truncation behavior at the 50-item cap.

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 that packs scope, ordering, and return content without a wasted clause. Nothing repeated from the schema or annotations.

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

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

With no output schema, the description usefully enumerates returned fields and the default ordering, which is the main thing an agent needs here. The gap is result-set sizing: no mention of default or maximum count despite a 50-item cap.

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 50%: site_id is documented inline, but limit carries only constraints (default 20, max 50) with no prose. The description reinforces the site-vs-organisation scoping but says nothing about limit or result-set sizing, so it does not fully 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 ('Recent audits... for one site or the organisation') plus the ordering and the fields returned, so the agent knows this is a collection read rather than a single-record fetch. It does not explicitly name sibling tools like audit.audit.get or audit.audit.create, leaving the list-vs-get distinction implicit.

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?

'For one site or the organisation' implies the two usage modes, but the description never states when to prefer this over audit.audit.get or when the result set is truncated. Context is implied rather than spelled out, with no exclusions or alternatives named.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context beyond that: the return is a full audit history of who acted and when, plus which observations opened, last saw and resolved the finding, and that mutation is impossible here.

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

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

Two tight sentences with no filler; the return-content statement leads and the constraint follows. Every clause carries information an agent can act on.

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 spends its words describing what comes back (history, observations, actors, timestamps), which is exactly the gap it must fill. It stops short of mentioning pagination or behavior for a missing/invalid finding_id, so it is strong but not exhaustive.

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 'finding_id' is never mentioned in the description, so no added meaning is supplied. The parameter is self-evident by name and typed/constrained in the schema, keeping this at the minimum-viable level rather than below it.

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

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

States a specific verb and resource ('Get' a 'finding') and defines scope as 'One finding', which implicitly contrasts with the audit.finding.list sibling. No sibling is named explicitly, but the singular-retrieval framing 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 closing sentence gives a clear negative boundary — state changes are not available through an assistant — which steers the agent away from attempting a mutation. It does not, however, explicitly say when to prefer this over audit.finding.list versus retrieving a known 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 readOnly/idempotent/non-destructive/non-open-world, so the load is light. The description adds real value beyond them by disclosing the returned data shape (state, severity, first/last seen, page and rule) and a security-relevant handling rule: page text is untrusted website content.

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, purpose front-loaded in the first clause with no padding. The second sentence's untrusted-content caveat is unusual phrasing but earns its place as a safety note.

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 sketches the return fields, but for a 4-parameter list tool at 25% schema coverage it omits how the filter parameters combine or what the limit controls. Adequate but with clear 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 25%, so the description must compensate, but it does not. It mentions 'state' and 'severity' as returned fields rather than as filters, and says nothing about 'limit' or 'site_id' as query parameters, leaving the filtering semantics to the bare 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 the resource (findings) and its granularity ('one finding per page per rule, across audits') plus the fields carried, so an agent knows exactly what it lists. It does not explicitly differentiate from the sibling audit.finding.get, relying on the list/get naming convention to imply the split.

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 the framing 'What is still wrong' and 'across audits' (i.e., outstanding cross-audit findings). There is no explicit when-to-use statement, no mention of audit.finding.get as the single-item alternative, and no 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 establish a safe read (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description earns credit by disclosing that only the *active* revision is returned (older revisions are not), that content is human-authored verbatim text, and that this resource is immutable via the assistant.

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 returned scope ('active revision') front-loaded before the read-only constraint. Nothing restates the title or repeats schema content.

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

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

No output schema exists, so the description carries the return-value burden; it conveys the semantic content (the rule's requirements text) but not the shape of the returned object (revision id, timestamps, requirement fields). Adequate for a one-parameter getter, but leaves the response format to inference.

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

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

Single parameter with 100% schema description coverage, so the schema already explains rule_id and its lineage semantics. The description adds nothing about the identifier format or sourcing; baseline 3 applies when the schema does the work.

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

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

The description names the resource precisely and adds scope detail: it returns the 'active revision' of a rule, specifically the requirement text in the owner's own words. That distinguishes it from history/revision siblings and from finding/site getters, though no verb is stated ('Get rule' must supply that framing).

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 schema note that rule_id is 'the rule id a finding names' hints this is called after reading a finding, and 'Rules cannot be changed through an assistant' implies a lookup-only workflow. No explicit when-to-use, prerequisites, or named alternatives 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, non-destructive and closed-world, so the safety profile is fully covered by structured data. The description contributes the field list returned for a site, which is real value given there is no output schema, but it says nothing about failure behavior (e.g. unknown site_id) or permissions.

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

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

A single short clause with zero filler and the returned-field summary front-loaded immediately. It is efficient, though the fragmentary style stops just short of actually stating the 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 one-parameter, annotation-covered read tool with no output schema, the definition is minimally adequate: the agent knows what to pass and what it gets back. It is missing error/not-found behavior and any differentiation from audit.site.list, which a peer 'get' tool should carry.

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

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

Schema coverage is 100% and the schema's own description already explains that site_id comes from audit.site.list. The description adds no meaning about the identifier's format or constraints, so the baseline 3 is appropriate.

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

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

The description names the resource ('One site') and enumerates the returned fields (address, status, timezone, crawl bounds), so an agent knows what data comes back. However the verb is only implied by the tool name, and it does nothing to distinguish itself from the sibling audit.site.list, which is the main selection hazard.

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 and no mention of the obvious sibling audit.site.list (list all sites) versus this single-site fetch. The only routing cue is the word 'One', which weakly implies a single-id lookup but never states it.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return content (sites plus crawl bounds) and the id hand-off to other tools, though it says nothing about pagination or result size 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?

Two tight sentences with no waste: the resource definition is front-loaded and the downstream id usage follows. 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 return-value burden, and it does describe the payload (sites with crawl bounds). For a zero-parameter list tool with full annotation coverage this is nearly complete, with only pagination/shape specifics left implicit.

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

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

The tool takes zero parameters (empty schema, additionalProperties=false), so there is nothing to document and the baseline is 4. No parameter meaning is missing or misdescribed.

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 and scope — 'the websites this organisation audits, with each site's crawl bounds' — so the agent knows it returns the org's site inventory plus crawl configuration. It does not explicitly distinguish itself from the sibling audit.site.get (single-site retrieval), leaving that inference to the name, but the resource is unmistakable.

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

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

Gives concrete downstream context: 'Ids from here go to audit.audit.create and the finding filters,' which tells the agent exactly when this call is the prerequisite step. It lacks an explicit when-not or a direct pointer to audit.site.get for single-site lookups, so it stops just short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the reporting window is the current calendar month in UTC, the data source is the organisation's billing account, and 'work in flight holds' is distinguished from consumed and free amounts.

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

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

It is a single, front-loaded sentence that opens with the resource and accounting period before enumerating fields. It is dense and long, but with no output schema the enumeration is load-bearing 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, the description carries the full return-value burden and does so reasonably well, listing each meter's allowance/used/held/remaining/charge and the two capacity limits. It stops short of describing the shape or units of those values, which keeps it out of the top band for a tool with no output schema.

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

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

Zero parameters, so per the rubric the baseline is 4. Schema coverage is 100% and additionalProperties is false, so there is nothing for the description 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?

Names a specific verb+resource (Ironfang Audit usage) and enumerates exactly what the response contains: per-meter free allowance, used, in-flight holds, remaining, settled pre-tax charge, plus org-wide capacity limits for sites and pages per audit. An agent can distinguish this from render.usage.get or the audit.audit.* siblings purely from the description.

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 an alternative, no prerequisites, and no exclusions. The most that can be inferred is that it reports the current calendar month, which is scope rather than guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds real value beyond them: it is free, requires no Ironfang Finance account, and itemizes what is returned including the conditional caveat that explanation fields exist only 'where Ironfang has reviewed the rule'. It stops short of covering error behavior for an unknown identifier.

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

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

Three sentences, front-loaded with the core action before the return payload and the usage routing. Every sentence carries information, though the return-field enumeration is dense 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?

With no output schema, the description carries the burden of describing returns and does so thoroughly: layer, family, severity, official reference, plain-language meaning, remediation, example fragment and documentation link, plus the conditional-review caveat. Combined with the read-only/free/auth context and the single fully-documented parameter, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% — the rule_id pattern, length bounds and case-insensitivity are all documented in the schema. The description only restates the semantics ('the identifier a finding names, such as BR-CO-10'), adding a source hint but no new format detail, 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 — looking up one EN 16931 / Peppol BIS Billing 3 validation rule by identifier — and gives concrete examples (BR-CO-10). It is clearly distinct from the plural sibling finance.rule.list and from audit.rule.get, which an agent can infer concerns audit findings rather than billing rules.

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

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

Explicitly says to use it to interpret a finding from the Ironfang Finance API or the free validator, which gives a clear trigger context. It does not, however, name finance.rule.list or any sibling as the alternative for enumerating rules rather than resolving one, so the when-not 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 already declare readOnly=true, idempotent=true, destructive=false, so 'Read-only, free' partly restates structured data; 'free' (no cost) is the only net-new behavioral fact. The paging behavior (offset/next_offset) is disclosed but largely mirrors the offset schema description. Modest added 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 dense sentence that front-loads the purpose and packs return fields, defaults, paging, and cost without wasted words. The clause chain with colons and semicolons reads slightly run-on, but it is information-dense rather than verbose.

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 (identifier, severity, family, title, documentation page) and covers defaults, filtering, and paging. Nothing essential for a read-only list tool is missing.

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

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

Schema coverage is 67% (above the 50% floor), and the schema already documents set, layer, family, and offset. The description reinforces 'filtered by layer, family or severity' but adds no syntax, format, or meaning beyond what the schema provides.

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

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

The description states a specific verb and resource ('The validation rules Ironfang Finance runs') and enumerates the returned fields, so an agent knows exactly what it produces. It does not explicitly distinguish itself from the sibling finance.rule.get (single-rule fetch), leaving that differentiation to inference.

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

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

It gives useful selection guidance for the 'set' parameter (default = reviewed explanations; set=official = every pinned-artefact rule), which is genuine when-to-use info. However, it never explains when to reach for this tool versus finance.rule.get or ruleset.list, and there are 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description still adds non-obvious context beyond them: the rulesets are immutable, calls are free, and document validation/generation must go through the REST API rather than MCP.

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 front-loaded sentences that lead with the resource, then the fields, then the identifier's purpose, then the out-of-scope routing. The field enumeration is long but load-bearing given there is no output schema; no sentence is pure 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 no parameters, the description carries the return-shape burden and does so by listing the fields returned, plus why the identifier matters and what the tool cannot do. Only minor gaps remain, such as ordering or result-size 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?

The tool takes no parameters (0 required, 0 optional), so there is nothing for the description to disambiguate. Baseline of 4 applies for a zero-parameter 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 and defines the resource precisely ('the immutable rulesets Ironfang Finance validates against'), then enumerates the fields each entry carries. It does not explicitly contrast with the nearby sibling finance.rule.list, so the rules-vs-rulesets distinction is left to inference.

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

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

It gives a concrete reason to call it ('A validation result names the ruleset it used, so this is how to read that identifier') and a clear scope boundary (validation/generation are not available through MCP; use the REST API). It stops short of naming the alternative tool an agent should prefer for rule-level data.

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

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

With readOnlyHint/idempotent/destructive already declared, the description goes well beyond them: usage is scoped to this connection's own calls, in UTC calendar month, per billing meter in each meter's own units, with 'used (committed)' vs 'reserved (held by work still running)' defined. It also discloses the negative behavioral fact that a connection has no allowance or budget of its own, which prevents a wrong mental model.

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

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

Three dense sentences, front-loaded with the resource and its contents, followed by routing and scope caveats. Every clause earns its place, though the parenthetical-heavy first sentence is more packed 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?

There is no output schema, so the description carries the burden of describing returns — and it does, covering identity, scopes, products, and meter-level usage with unit semantics. Combined with the explicit statement of what cannot be retrieved, an agent has everything needed to select and call it correctly.

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

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

The tool takes no parameters (schema coverage 100%, empty properties with additionalProperties:false), so the baseline is 4. There is nothing for the description to clarify parameter-wise, and it correctly adds no spurious argument language.

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 resource ('the current MCP connection') and enumerates exactly what it resolves to: organisation, scopes, products available, and this month's per-meter usage. It also names sibling tools (render.usage.get, audit.usage.get) so an agent can distinguish this connection-level view from org-level usage without opening any schema.

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

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

It routes the agent explicitly for usage/allowance needs ('The organisation's usage and free allowances are render.usage.get and audit.usage.get') and states a clear exclusion ('the billing account itself... cannot be read through a connection'). What is missing is a direct 'use this when you need the scopes/products/identity of the current connection' statement, but the boundaries are otherwise well drawn.

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

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

Goes well beyond the annotations by disclosing the all-or-nothing admission model ('if any item is refused, the whole batch is refused with the billing code') and per-item billing behavior ('Each job then counts only if it succeeds'). These are material side effects not derivable from readOnlyHint/idempotentHint alone.

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

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

Front-loads the core action in the first sentence and keeps to four dense, information-bearing sentences with no filler. Slightly crowded, but every sentence contributes distinct 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?

With no output schema, the description compensates by explaining the async polling flow (render.batch.get) and the admission/billing outcome. It omits auth requirements and the delivery behavior details, but is otherwise complete for a write tool of 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 coverage is 60% and the description's param-level additions ('shared default and optional delivery', up to 100 items) largely restate what the schema already encodes. It clarifies the item kind and the default-nesting behavior only marginally, so baseline 3 is appropriate against a partially documented 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 ('Submit up to 100 screenshot or PDF jobs together') and scopes it precisely, distinguishing it from the single-job siblings by noting each item is 'one render.screenshot or render.pdf each'. An agent can tell this apart from render.screenshot.create and render.pdf.create without opening a schema.

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

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

Gives clear operational context: use this to submit multiple jobs at once, and 'Poll render.batch.get for progress and each job's result' names the follow-up tool explicitly. It lacks an explicit when-not-to-use (e.g. prefer the single create for one job), but the batch-vs-single distinction is strongly 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: it discloses the return payload shape (counts by status, completion flag, per-job state/usage/result link), which matters because there is no output schema. It omits any note on polling cadence, pagination, or behavior for an unknown/expired batch 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?

One compact sentence, front-loaded with the resource ('A batch's progress') before the detail. No filler sentences. It is a noun-phrase fragment rather than a full sentence, and the trailing 'result link once succeeded' is slightly awkward, but 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?

With no output schema, the description correctly takes on the burden of describing the return payload, and it does so for the main fields. Combined with annotations that fully cover the safety profile, an agent has enough to call it correctly. Missing only edge-case behavior (invalid id, terminal failure states, result link availability timing).

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 parameter with 100% schema description coverage ('A batch id returned by render.batch.create'), so the schema already carries the semantics. The description adds nothing about batch_id format, lifetime, or invalid-id behavior, so this sits at the baseline for a fully documented 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 names a specific resource (a batch) and enumerates exactly what is returned: status counts, a done flag, and per-job state/usage/result link. That is more informative than the title 'Get batch'. It does not, however, explicitly distinguish itself from the nearby render.job.get or render.batch.create siblings, leaving the agent to infer the batch-vs-single-job 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?

Usage is only implied: the 'whether it is done' clause hints at polling a batch after render.batch.create, but there is no explicit when-to-use, no exclusions, and no named alternative such as render.job.get for inspecting one job. The agent can guess the workflow but is given no routing guidance.

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

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

Annotations declare it is a non-read-only, open-world, non-idempotent mutation, but the description adds genuinely new behavior: it is always asynchronous, must be awaited via render.job.get, and carries a per-output-second billing model (rounded up) with specific pricing keys tied to output size. This is exactly the kind of cost and lifecycle disclosure annotations cannot convey.

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

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

Three front-loaded sentences with no filler; the core action and constraints come first and the async/pricing details follow. The final pricing sentence is dense with two SKU keys and four enums but remains readable and earns its space.

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

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

With annotations covering the safety profile and an output schema covering the return shape, the description is left to explain lifecycle and cost, which it does. Minor gaps remain around caption/font behavior, but nothing critical to invoking the tool correctly is missing.

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

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

Schema description coverage is 43% across 7 parameters, so the description must compensate. It clarifies that background accepts image/video and that omitting it yields solid colour, and it maps the size enum to pricing tiers (vertical/landscape to FHD, square/720p to HD), but leaves colour, font_size, external_id, and the captions structure unexplained.

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 (short captioned video clip), duration bound (1-60 seconds), and overlay medium (public image, video or solid colour). This clearly distinguishes it from sibling render.* tools like render.pdf.create, render.screenshot.create, and render.qr.create.

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

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

Gives explicit async workflow guidance: it's always a durable job and the agent should request a task or poll render.job.get. It does not, however, contrast this with alternative creation paths such as render.batch.create or render.template.render, so sibling selection 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?

Goes well beyond annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing that the signing secret is returned exactly once and never again, plus the operational instruction to hand it to the endpoint operator. This one-time-secret behavior is a critical trait not encoded anywhere else.

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 the tool does, followed by the payload/secret behavior and the sibling exclusions. 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 compensates by stating what the caller receives (the one-time signing secret). Combined with the exclusion note for S3 destinations, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents 'url' (public https, private networks refused) and 'name'. The description adds no syntax, format, or validation 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?

States a specific verb (Register) and resource (https webhook destination), and clarifies the exact trigger ('when jobs finish'). It distinguishes itself from render.destination.list/delete/test and from S3 destinations, which are routed elsewhere.

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

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

Explicitly names the when-not case: S3 storage destinations carry credentials and are registered in the portal, not through an assistant. This routes the agent away from an unsupported path and names the correct 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 destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description adds genuinely useful scope information: existing job delivery records are retained and no new deliveries are sent. It effectively tells the agent the destruction is partial rather than a hard purge, which annotations alone cannot convey. It stops short of stating permission requirements or behavior when the id is unknown.

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 primary effect (stop deliveries, forget the destination) and followed by the retention caveat. 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 one-parameter destructive tool with rich annotations and no output schema, the description covers the essential behavioral question: what happens to already-referencing jobs. Missing only minor details such as the error/behavior for an unknown destination id or required authorization, which the idempotent hint partially covers.

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

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

Schema description coverage is 100% and the sole parameter's schema description even points at render.destination.list as the id source, so the schema carries the load. The description adds no format or id-resolution detail beyond that. Baseline 3 is appropriate.

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

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

The description states a specific effect on a specific resource: deliveries to the destination stop and the destination is removed. It distinguishes itself from siblings such as render.destination.test (which also touches deliveries) and render.destination.list/create by describing a permanent removal rather than a probe or a creation.

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 — call this when you want to stop deliveries and drop the destination — but no explicit when/when-not condition or alternative (e.g. test the destination first, or check jobs still naming it) is offered. Note the description does clarify that jobs already naming it are unaffected, which nudges toward a 'safe to delete anytime' reading.

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 closed-world, so the safety profile is fully covered. The description usefully adds what a destination actually is and where destinations come from (portal or render.destination.create), but says nothing about pagination, result ordering, or what an empty list means.

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

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

Two tight sentences with no filler, and the important downstream fact (ids feed a create tool's delivery block) is stated up front-ish. Opening with a resource definition rather than 'Returns the destinations...' is slightly indirect but costs nothing.

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, closed-world list tool with annotations carrying the safety profile, the description covers what the resource is, how items get registered, and how the returned ids are consumed. The absence of an output schema means a note on return shape or pagination would help, but the essential call-time information is present.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no schema surface for the description to compensate for. Nothing in the text is needed to parameterize the call, and nothing misleads.

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 precisely defines the resource this tool enumerates — webhook endpoints and storage buckets where finished renders are delivered — and distinguishes it from render.destination.create, which registers them. It never states the verb 'list' explicitly, but the resource identity is unambiguous and an agent can place it confidently among the destination siblings.

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

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

It supplies workflow context — 'Ids from here go in a create tool's delivery block' — which implies this is a lookup to run before invoking render.destination.create. However, it never says when to prefer this over render.destination.test or render.destination.delete, and gives no prerequisites or exclusions, 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?

Goes beyond the annotations by disclosing a non-obvious result contract: an unanswered destination still returns a successful call with ok=false plus a reason, so the agent won't treat a failed probe as a request error. Annotations already cover the safety profile (destructiveHint=false, idempotentHint=true), and the description adds real value on top. It does not mention rate limits, usage accounting, or logging for test deliveries.

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 the action front-loaded and the surprising result semantics immediately after. Every clause earns its place; nothing is repeated from the schema 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 single-parameter probe with no output schema, the description covers the one thing an agent could misread — that a non-answering destination is not a failed call — and passes on a useful reason string. It lacks only detail on timing (sync vs async) and whether the test is recorded or billed.

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 destination_id is fully documented there, including the cross-reference to render.destination.list. The description adds no extra meaning about the identifier, so the baseline 3 applies.

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

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

States a specific verb and action — 'Send a test delivery now and report what happened' — against the destination resource named in the tool name/title. No sibling (destination.list/create/delete) performs a test delivery, so the tool is distinguishable in practice, though the description never explicitly contrasts itself with those neighbors.

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 this is for verifying a destination before relying on it, but the description never says when to call this versus render.destination.create/list or whether a test is required before real deliveries. No exclusions, prerequisites, or alternatives 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 signal a destructive, idempotent, non-read operation. The description adds genuinely new behavioral context: it is a 'cooperative' cancel (a request, not a hard kill) and it describes billing/quota consequences ('queued work counts nothing; running work counts only if it produced a usable output'). That is value beyond the annotations.

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

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

Two tight sentences, front-loaded with the action and scope, followed by the billing consequence. Every sentence earns its place with no filler.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description covers the cooperative nature and quota impact, leaving only minor gaps like failure modes when a running job cannot be cancelled.

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 job_id is documented in the schema as 'A job id returned by a create tool.' The description adds no further parameter meaning, 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 (cancel) and resource (render job), and further qualifies the applicable states ('queued or running'). It's clear enough to distinguish from render.job.get and other render siblings, though it doesn't explicitly name a sibling it might be confused 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?

Implies usage by scoping to 'queued or running' jobs, which tells the agent when the tool applies. However, it gives no explicit when-not-to-use guidance, no prerequisites, and no alternatives if the job isn't cancellable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, non-destructive, closed-world, so the safety profile is fully covered. The description adds genuinely useful domain context the annotations cannot: that the download link is short-lived and only present once the job succeeds, and that usage counters are scoped to the organisation. That is value beyond structured fields, but permissions, rate limits, and expiry specifics are still absent.

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 that front-loads the core purpose (the state of a render job) then layers the usage-accounting and result details. Efficient, though the nested parenthetical makes for a slightly heavy read rather than a crisp scannable 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?

With an output schema present the description need not explain return shapes, and it instead flags the two conditional aspects an agent must handle: download link is short-lived and only appears on success, plus org-scoped usage accounting. Complete enough for a single-parameter read tool, though polling/eventual-consistency behaviour before success is unaddressed.

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

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

Only one parameter (job_id) and schema coverage is 100%; the schema already documents that it is a job id from a create tool. The description adds the scoping notion that the job must have been created through this connection, but no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (get) and resource (the state of a render job created through this connection), and enumerates exactly what the returned state contains: usage accounting (meter, quantity admitted, committed) and result metadata plus download link on success. An agent can distinguish this from render.usage.get and render.batch.get at a glance.

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 guidance on when to use this versus render.job.cancel, render.usage.get, or render.batch.get. The phrase 'created through this connection' implies a scope constraint but never states a when-to-use or when-not-to-use condition, 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 mutation (readOnlyHint=false), non-idempotence, and open-world access, so the bar is lower. The description adds genuinely useful context the annotations cannot convey: it is queued as a durable job, and usage billing semantics (one render.pdf per success, nothing on failure). It stops short of auth requirements or delivery prerequisites.

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 compact sentences, front-loaded with the core action and followed by the two facts an agent most needs (async job, billing). 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?

An output schema exists, so return values need no explanation, and the billing/async behavior is covered. However, with 7 parameters at 14% schema coverage on a mutation tool, the description leaves meaningful gaps about the inputs it accepts.

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 14%, so the description must compensate for seven largely undocumented parameters (url, html, landscape, external_id, paper_format, print_background) and it does not. It never explains the url/html exclusivity, sizes, or page-format options, leaving the schema's oneOf and defaults to speak alone.

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 (Render) and resource (public web page or raw HTML) with an explicit output type (PDF). This cleanly distinguishes it from siblings like render.screenshot.create and render.template.render 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?

Usage is implied (render a PDF) and the phrase 'public web page' hints at an input constraint, but no alternatives are named and no when-to-use vs render.screenshot.create, render.template.render, or render.batch.create is given. Neither is there any guidance on choosing url vs html.

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 idempotency, non-destructiveness and closed-world scope, so the description's added value is the billing disclosure ('counted on render.qr, a free utility that is never charged') and the inline data-URL return, both useful traits beyond the structured fields. It does not note any size/rate limits on the 2048-char input.

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

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

Two tight sentences with no filler; the core behavior and return format are front-loaded and the billing note is a short trailing clause.

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

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

An output schema exists, so return-value detail is unnecessary, and the description covers purpose, input domain and cost. The one shortfall is the undocumented non-required parameters, though their enums/defaults/constraints in the schema partially backfill that 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 only 17% — just the `data` field is documented — so the description must compensate and it does not. It mentions text/URL (mapping to `data`) but says nothing about size, format, background, foreground, or error_correction, leaving five parameters to be inferred from enums and defaults alone.

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 ('Generate a QR code image') plus the accepted input domain (text or URL) and the return form (inline data URL). This clearly distinguishes it from sibling renderers like render.screenshot.create and render.pdf.create without opening any schema.

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

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

The description implies when the tool is relevant ('for text or a URL') but never names an alternative or states when NOT to use it (e.g., bulk generation via render.batch.create). Usage is inferable rather than explicit.

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

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

Adds real context beyond the annotations: durable job queuing, the required polling step via render.job.get, and the billing rule that successful captures count against usage while failures do not. It does not mention auth requirements or rate limits, but the billing/async disclosure is substantive.

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

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

Three tight sentences, front-loaded with the core action before the async and billing caveats. No filler; every clause carries information.

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

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

An output schema exists so return values need not be described, and the polling pointer compensates for the async nature. However, with 13 parameters and low schema coverage, the description leaves several behavioral and parameter aspects undocumented for a fairly complex capture tool.

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

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

Schema description coverage is only 46% across 13 parameters, so the description must compensate and largely does not. It alludes to the url/html oneOf by saying 'public web page or raw HTML', but adds no detail on the undocumented width, height, device, format, selector, or delivery semantics.

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

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

States a specific verb and resource: capturing a public web page or raw HTML as an image. It distinguishes itself from render.pdf.create and render.qr.create by naming the image output, though it does not clarify how it differs from the closely related render.clip.create 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?

It explains the asynchronous workflow (queued job, poll render.job.get) which is genuine usage guidance, but never states when to prefer this over render.clip.create, render.pdf.create, or render.template.render for overlapping tasks. Usage is implied rather than 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?

Adds substantial context beyond the annotations: creation is free, each fetch incurs exactly one render.screenshot or render.image, it bills the organisation (not this connection), and lifetime is capped at 24 hours. This is precisely the kind of billing and side-effect disclosure the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) cannot convey.

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

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

Three compact sentences with the core action front-loaded and no filler. Slightly dense wording in the billing sentence, but every clause carries information.

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

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

An output schema exists, so return values need not be documented, and the description covers the billing model, lifetime cap, and render target. It stops short of clarifying the kind-to-parameter relationship (url vs template_id) and when to prefer this over the immediate-render siblings.

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 38% across 8 parameters, so the description should carry more weight than it does. It does explain ttl_seconds semantics (24h cap, no permanent links) and links the render target to kind, but width, height, full_page, and variables are left entirely to the schema with no added meaning. Baseline 3 given the partial compensation.

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 signed URL that renders a screenshot or template when fetched') with the deferred-rendering model made explicit, which separates it conceptually from render.screenshot.create and render.template.render. It never names those siblings outright, so the differentiation is implied rather than stated.

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

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

The description hints at when this is appropriate (a URL you hand off that renders later) and constrains lifetime to 24h via MCP, but gives no explicit rule for choosing it over render.screenshot.create or render.template.render. Usage is inferable, not 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 readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds genuinely new information by disclosing the returned fields (id, name, size, variable names), which is valuable since no output schema exists. It does not mention error behavior for a missing id, keeping it short of 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?

One short noun phrase with zero padding and the return fields front-loaded. It is efficient, though the fragment style skips a verb and reads more like a field list than a sentence.

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

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

For a single-parameter, fully-annotated read tool with no output schema, the description covers purpose and return shape adequately. Only the not-found/error behavior and any sibling routing are absent, which are 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?

There is a single parameter with 100% schema description coverage, and the schema itself explains that the id comes from render.template.list. The description adds nothing about the parameter, so the baseline of 3 is appropriate.

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

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

The description names the resource (one template) and enumerates exactly what is returned (id, name, size, variable names), which lets an agent distinguish it from render.template.list and render.template.render. The verb is only implied via the tool name ('get'), so it is clear but not maximally 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?

No statement of when to use this tool versus the sibling render.template.list (enumerate) or render.template.render (use it to produce output). The only routing hint ('A template id from render.template.list') lives in the schema description, not in the tool description, so the description itself offers no 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, idempotentHint and non-destructive, so the safety profile is covered; the description adds genuine value beyond that by disclosing the shape of the result set and by explicitly bounding its scope ('never the template markup'). It stops short of mentioning pagination or result ordering, which for a list endpoint would be 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 sentence, front-loaded with the resource, and every clause earns its place: the field list tells the agent what it will get and the closing clause rules out the one thing agents might wrongly assume (markup).

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 no parameters, the description carries the return-value burden and does so adequately by enumerating the fields. For a zero-argument list tool only ordering/pagination behavior is left unspecified, which is a minor 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?

The tool takes zero parameters, so the schema-to-description burden is nil and the baseline of 4 applies. Nothing in the description misrepresents or adds confusion about inputs.

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

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

States the resource specifically ('the organisation's Ironfang Render templates') and enumerates the fields returned (id, name, size, expected variable names), which is far more concrete than restating the name. It implicitly separates itself from render.template.get by asserting it never exposes template markup, though it doesn't name that sibling 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?

Usage is implied rather than stated: by promising 'never the template markup', an agent can infer that markup requires render.template.get or render.template.render, but no explicit when-to-use or when-not-to-use condition is given for choosing among the template 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 declare a non-read-only, non-idempotent, closed-world write, and the description adds genuinely useful context beyond them: the work is a durable queued job and consumes one render.image quota per success. That billing and async semantics are exactly the extra behavioral facts annotations cannot express.

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

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

Three short sentences, front-loaded with the core action before the async and quota details. Every sentence carries information, though the middle sentence is telegraphic and could be folded in.

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 queued creation tool, the async + quota disclosure plus the existing output schema cover the return path adequately. However, with zero schema description coverage and a nested variables object, an agent still lacks enough to build a correct call, so the definition is only minimally viable.

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 four parameters including a nested 64-property variables object, yet the description says nothing about template_id, format options, variable key/value constraints, or what external_id is for. The single mention of 'variables' is generic and adds no meaning beyond the parameter name.

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 (organisation templates with variables) with a concrete output type (image). It is distinguishable from render.template.get/list and the other render.* producers, though it does not explicitly name or contrast with render.pdf.create or render.screenshot.create.

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 statement of when to choose this over render.pdf.create, render.screenshot.create, or render.batch.create, and no prerequisites (template must exist, variables must match the template schema) are given. The only usage signal is implicit: it is queued, so the caller learns it is asynchronous.

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, idempotent, non-destructive, closed world), so the bar is lower. The description still adds real value: it names the billing-account scope, the UTC calendar-month window, the month-start renewal cycle, and the accounting semantics (in-flight work holds against the allowance; the charge is pre-tax). It stops short of noting auth requirements or call 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?

Two sentences, resource and time scope front-loaded, with the renewal rule kept to a separate trailing sentence. The middle enumeration is dense but every listed dimension earns its place by telling the agent what will come back.

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 explaining the return shape — and it does so, listing meters and their fields and the pre-tax framing. Nothing an agent needs to call and interpret this tool is missing.

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

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

The tool takes no parameters, so the baseline is 4; there is no parameter semantics to add or omit. The schema is an empty object with additionalProperties false, which the description correctly mirrors by describing a parameterless query.

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

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

States a specific verb (get) and a tightly scoped resource: the organisation's Ironfang Render usage for this calendar month, sourced from its billing account. It even enumerates the returned dimensions (free allowance, used, in-flight holds, remaining free, settled pre-tax charge), so an agent can tell it apart from audit.usage.get 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?

Usage is implied — an agent can infer you call this to inspect current-month Render consumption — but there is no explicit when-to-use, no exclusions, and no pointer to the audit.usage.get sibling for non-Render usage. The renewal note adds temporal context but not 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 only say non-readonly, non-idempotent, non-destructive, open-world. The description goes well beyond: the token is single-use with a ten-minute lifetime, is returned exactly once, must be held in IRONFANG_CONNECT_TOKEN rather than a file/log/history, and the cloud never selects a destination. That is exactly the security and lifecycle context an agent cannot get from annotations.

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

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

The purpose is front-loaded in the first clause and each following sentence carries a distinct operational fact (result contents, secret handling, trust boundary). It is dense and slightly long, but none of the sentences are 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 compensates by enumerating what the result carries: the token, the gateway to dial, the completion command with a 127.0.0.1 target per route label, and the release to verify. Combined with the secret-handling and trust-boundary notes, an agent has enough to call and use 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?

Schema coverage is 67%, and the schema itself already documents both `name` and `routes` (binding and default-to-all-labels). The description adds only the target format (http://127.0.0.1 per route label), which is marginal beyond the schema. Baseline 3 is appropriate.

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

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

The description states a concrete verb and artifact: "Mint a single-use, ten-minute bootstrap token" so a local connector can forward callbacks. An agent immediately knows this produces a credential-bearing bootstrap payload. It does not explicitly contrast itself with the closest sibling, rig.connector.status, 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?

It gives clear context for use (firing up `ironfang rig connect` on this machine to forward the run's callbacks) and states a hard constraint: the connector forwards only to targets named on its command line. There are no explicit when-not conditions or named alternatives (e.g. when to prefer rig.connector.status), so it is context-rich but not fully 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 this is a safe, idempotent, non-destructive read, so safety is covered. The description adds the useful behavioral detail that this is a poll target and that waiting-callback counts are tracked, but says nothing about return format or how often to poll.

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 no filler; the return content comes first and the usage timing follows. Slightly awkward phrasing ("whether one is online", "callbacks wait for one") but no wasted text.

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

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

With no output schema and a single well-documented parameter, the description usefully compensates by naming what is returned (connector online status, queued callbacks) atop the safety annotations. Complete enough to call correctly, though it omits any detail about poll cadence or error states.

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 (run_id) and schema description coverage is 100%, so the schema fully documents it and the description adds no parameter-level meaning. Baseline 3 is appropriate when the schema does the work.

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

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

The description conveys the specific resource (the run's connectors) and the data returned (online state and count of waiting callbacks). It lacks an explicit verb but an agent can infer this is a status query over rig connector state, distinguishing it from rig.connector.prepare and the event tools.

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

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

"Poll this after starting ironfang-connect, before triggering the callback" gives a concrete when-to-use condition tied to a specific workflow step. It stops short of naming an alternative tool or a when-not-to-use case, so it lands just below the top tier.

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, idempotent=true, destructive=false and closed-world, so the safety profile is covered. The description goes beyond that by disclosing that event payloads are third-party input labelled untrusted and by explaining the paging contract via `next_since`. That is genuinely useful context not present in the annotations or 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 dense sentences, zero filler, with the scoping rule (sequence order after `since`) front-loaded, followed by content enumeration, the untrusted-data warning, and the paging hint. Every sentence carries load.

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 carry the return-value burden, and it largely does: it describes what each event contains, its ordering, and the `next_since` cursor. The untrusted-data label covers a security concern an agent needs. Only the `limit` parameter and the exact response shape remain unaddressed.

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

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

Schema coverage is only 33% (`since` is documented, run_id and limit are not), so the description is expected to compensate. It clarifies `since` semantics and introduces `next_since` for paging, but says nothing about `limit` (max 200) or the run_id requirement. Partial compensation only, 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 names a specific resource (the run's timeline of events) and scopes it (sequence order after `since`), then enumerates the concrete content types: mail, callbacks, mock calls, forwarding results, faults. An agent immediately knows this is a read of recorded events. It stops short of naming how it differs from siblings like rig.event.wait or rig.event.replay, so sibling 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?

Usage guidance is implied rather than explicit: it tells you to page with `next_since` and that ordering is by sequence after `since`, which is enough to call it. But it never states when to prefer this over rig.event.wait (live waiting) or rig.event.replay (re-execution), which are the closest alternatives. Adequate but with a clear routing gap.

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

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

Adds substantial context beyond the annotations: the side-effect records created (callback.replayed, plus callback.forwarded and connector.request.completed appearing against the original event id), the fact that faults do not act on a replay, and a hard cap of 200 per run. These are operational constraints the annotations cannot express.

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

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

Front-loads the action and goal, and every subsequent sentence carries a distinct operational fact (preconditions, recording behavior, fault exemption, rate cap). The opening sentence is long and compound, but nothing is redundant.

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

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

For a two-parameter, no-output-schema tool, the description covers purpose, preconditions, side effects, and limits completely. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 50%: event_id is documented in the schema, run_id is not. The description compensates meaningfully by constraining what event_id may be (a callback.received on a connector route with an active run; obtained from rig.event.list or rig.event.wait), which is more than the schema states.

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 ('forward a callback ... to its connector route again, exactly as recorded') plus the intent (proving idempotence). It is clearly distinguishable from siblings like rig.event.list, rig.event.wait, and rig.connector.prepare.

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

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

Gives explicit preconditions: the event must be a callback.received on a resource with a connector route, and the run must be active. It does not name the alternative tool for fetching candidate event ids in prose, but the schema description for event_id points to rig.event.list / rig.event.wait, so routing is covered.

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

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

Adds real behavior beyond the annotations: blocking semantics, determinism, and the crucial detail that a timeout yields matched:false with next_since rather than an error. Some of this (timeout default/range) duplicates the schema, but the blocking/determinism semantics are unique.

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

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

Four sentences, front-loaded with the core behavior, and each sentence earns its place (scoping, determinism, timeout contract, alternative). 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?

No output schema exists, so the description must carry return-value context; it explains the timeout return shape but not the success return shape. For a 6-param blocking tool, it is otherwise 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 already 83%, so the schema documents most parameters. The description implies type/resource/match/since but adds little syntax or format detail beyond what the schema provides; 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 (block/wait) and resource (event) plus the exact scoping conditions (type, resource, matching fields, after `since`). It explicitly distinguishes itself from the sibling by routing away from polling rig.event.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 explicit when-to-use guidance ('Prefer this to polling rig.event.list') and names the alternative. It also nails the follow-up case: on timeout, wait again from next_since rather than erroring.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses that the manifest records a recomputed event hash chain and how it is signed, that a download path is returned, and that the call is free. The 'read-only' clause is redundant with the annotation, keeping 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?

It is a dense, comma-heavy sentence, but the return contents are front-loaded and each clause (file inventory, hash chain, signing, download path, access mode) carries distinct information. Slightly over-stuffed, but no sentence is wasted.

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

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

With no output schema, the description must carry the return contract, and it does: it enumerates the manifest's contents, the hash-chain recomputation, the signing record, and the download path. An agent has enough to know what comes back and what the artifact is for.

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 run_id parameter is documented as 'A run id from rig.run.create.' The description adds no syntax, format, or sourcing detail beyond the schema, so the baseline of 3 for a fully-covered single parameter is appropriate.

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

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

The description names the resource precisely ('the manifest of a run's evidence bundle') and enumerates what the manifest contains — the run, counts, files with sizes and SHA-256, hash chain, signature, download path. It is clearly a read of a specific artifact, not a generic list. It doesn't distinguish itself from the sibling rig.evidence.receipt, 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?

The only contextual cue is that the bundle 'is a ZIP for a person or a CI step to fetch with the CLI or a platform key', which hints at audience but not tool selection. There is no guidance on when to call this instead of rig.evidence.receipt, rig.run.get, or rig.event.list, nor any prerequisite 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 read-only, idempotent, non-destructive, so the safety profile is covered. The description adds genuine behavioral context: signing is conditional ("when it has one"), the signature embeds the key, and the receipt reflects the event hash chain head. It does not discuss pagination or failure modes, but for a read-only receipt that is minor.

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

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

Three sentences, front-loaded with the core artifact and its contents before branching into signing and usage. Dense but every clause carries distinct 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?

There is no output schema, so the description carries the burden of explaining the return value — and it does so thoroughly (contents, signature, key provenance). Combined with annotations covering safety and full parameter coverage, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single run_id parameter is fully documented in the schema. The description adds no format, length, or sourcing detail beyond the schema's "A run id from rig.run.create," 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?

The description names the exact artifact produced (a signed statement of a run) and enumerates its contents: project, suite/version, status/outcome, verdicts, event count, and hash-chain head. It also differentiates from the sibling rig.evidence.export by explaining that the signature is what makes this a proof artifact.

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?

"Give this to whoever needs proof of what the run did" states the audience and the situation, and it references related surfaces (rig.evidence.export's manifest, GET /rig/v1/evidence/keys) for key naming. It stops short of an explicit when-not-to-use or a direct either/or against the 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 cover the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds real behavioral context beyond them: firing on the next matching observation, count-limited or until removed, and every firing emitting a fault.injected timeline event. It omits auth requirements and the exact interaction with persistent/run-end lifecycle, keeping it below 5. No contradiction with destructiveHint=false.

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

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

Two dense sentences, front-loaded with the core action and followed by the when-to-use rationale. The long enumerated middle clause is information-rich but borders on run-on, slightly hurting scannability.

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 12-parameter mutation tool with no output schema and rich schema documentation, the description covers the fault-type taxonomy, firing/lifecycle semantics, and event emission. It leaves resource-compatibility rules and count/persistent interplay to the schema, which is acceptable given the high coverage.

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 83%, above the 80% threshold, so baseline is 3; the description goes further by mapping the 'type' enum values to their observable effects (delay/duplicate/drop/reorder/payload mutation vs. status override, connection reset, bandwidth throttle, partial cut-off). It does not spell out per-parameter constraints already present in the schema, so 4 is fair.

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 (arm deterministic interference on one resource of an active run) and enumerates the concrete fault families, so an agent can immediately distinguish it from rig.fault.remove. The title 'Arm a fault' and description align.

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

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

'Use to prove the application survives duplicates, delays, reordering, corrupted payloads and dependency failures' gives a clear purpose-driven context for when to reach for it. It does not, however, explicitly name the alternative sibling (rig.fault.remove) or state exclusions, so it falls 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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a genuinely non-annotated behavioral fact: the fault's history remains on the timeline, confirming that removal is a disarm rather than a destructive delete. It still says nothing about permissions, error cases, or whether the fault can be re-armed.

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

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

Two short sentences with zero filler, and the core effect is front-loaded before the history-retention detail. 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 simple two-parameter mutation with no output schema, the description covers purpose and the key post-condition (history preserved). However, with 0% parameter coverage it should do more to explain run_id/fault_id scope, and it omits any note on failure or repeat-call 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 0% and neither of the two required parameters (run_id, fault_id) is mentioned in the description, so no meaning is added beyond the bare property names. The description leaves the agent to infer how a fault is identified and in what scope.

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?

"Disarm a fault so it fires no more" gives a specific verb plus resource and states the operational effect, making it clearly distinct from the sibling rig.fault.add. It does not, however, name that sibling or any other tool to differentiate against 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 by the effect clause: an agent can infer you disarm a fault when it should stop firing, and the counterpart rig.fault.add exists in the sibling list. There is no explicit when-to-use statement, no exclusions, and no mention of prerequisites such as the run needing to be active.

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 non-read, non-destructive, non-idempotent write, so the description is not carrying the safety burden alone. It still adds real context annotations cannot encode: the project is 'permanent' (irreversible) and 'costs nothing' (no billing impact).

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 is front-loaded and the gating condition and behavioral facts follow 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?

For a two-parameter create call with annotations present and no output schema, the description is nearly sufficient, covering purpose, precondition, and key behaviors. It omits the undocumented 'name' parameter and the failure mode when a slug already exists, which are the only 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 50%: slug is documented in the schema, but name is not explained anywhere. The description adds no parameter meaning at all, so the half of the schema left bare remains bare.

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 project') and narrows the scope to 'one application', so the agent knows exactly what is produced. It also names the sibling rig.project.list, letting an agent distinguish it from read paths 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?

'Use when rig.project.list has none that fits' gives a concrete precondition and points at the alternative tool to check first. It stops short of stating exclusions or what to do on slug collisions, but the selection condition is unambiguous.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description still adds genuinely new context not present in the annotations: the call is 'Free' (no cost incurred) and 'nothing changes.' Terse, but it does add beyond the structured fields.

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, front-loaded fragments with zero waste: what projects are, where their ids go, and what the call costs. 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 no-arg, read-only list tool with no output schema, the description covers what the resource is, its downstream use, and its side-effect/cost profile. It does not describe what is returned, which is a minor gap since no output schema exists to carry that information.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It correctly adds no parameter noise.

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 and defines it concretely ('Ironfang Rig projects: the persistent containers suites live in'), which is more than a restatement of the title. It stops short of an explicit verb ('list all'), though the name and title supply that.

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?

'Ids from here go to rig.suite.upsert' gives a downstream routing hint, but there is no statement of when to call this versus alternatives (e.g. rig.suite.list) and no prerequisites or exclusions. 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 write/openWorld/non-idempotent/non-destructive, but the description adds real behavioral context beyond them: public-Internet exposure ('as for rig.run.create'), quota impact ('each interaction it accepts counts one rig.interaction'), and lifecycle ('lives until the run ends'). No auth/permission detail, but this is substantive added value.

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 verb and resource scope come first, with secondary facts (internet effect, interaction counting, lifetime) trailing. Only one awkward run-on sentence and a fragment; no filler, though a bulleted type list would scan faster.

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 7-parameter, nested-object, mutation tool with no output schema and no annotations-level detail beyond hints, the description covers purpose, dynamic-vs-declared scope, side effects and lifetime. It leaves return-value expectations and permission requirements unstated, which is a modest gap given there is no output schema to compensate.

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 71%, so most parameters carry their own descriptions. The description still adds value by translating enum values into intuitive terms (inbox=email, callback URL=callback, mock with rules=mock_http, route label=connector_route) and by calling out the optional callback forwarding to a connector route, which helps an agent choose the right type and shape the request.

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 ('Allocate one more resource on an active run') with a concrete enumeration of what can be allocated (inbox, callback URL, mock with rules, route label) that maps onto the type enum. The 'beyond what the suite declared' clause sharpens the scope so an agent can distinguish this from suite-level declaration tools like rig.suite.upsert.

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?

Clear context for use: on an *active* run, for resources not already declared in the suite, with the connector-route variant called out. It does not, however, name an alternative tool or state when-not to use it (e.g., why not declare it in the suite instead), so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the state effect ('end without an outcome') and an equivalence note, but does not say what is destroyed or whether the run becomes unrecoverable/purged.

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

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

Two sentences, front-loaded with the core action before the qualifying context. The second sentence ('Same effect as finishing on the run's addresses') is somewhat cryptic but short and adds a behavioral note.

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 annotations covering idempotency and destructiveness and no output schema, the description covers the action and a usage context. It leaves the required run_id and the reason parameter unexplained, which is a real 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 0% and the description mentions neither of the two parameters. The required run_id and the optional 200-char reason are left entirely to the schema, 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 and resource ('End a run without an outcome') and implies differentiation from rig.run.finish by contrasting 'without an outcome' against a normal finish. It never names the sibling, but an agent can infer the cancel-vs-finish 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?

'for a test that was abandoned' gives a clear when-to-use context. There is no explicit when-not clause or named alternative (e.g. rig.run.finish), but the abandoned-test framing is a usable selection signal.

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

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

The description contradicts the annotations: it states 'Idempotent per call' while idempotentHint is declared false, a direct conflict on repeat-call semantics. The otherwise rich disclosure (public-internet exposure matching openWorldHint=true, non-destructive, non-read-only, ttl bounds, capacity/billing effects) is undermined by this inconsistency.

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, then layers effects and caveats; each sentence carries real information. It is dense and slightly packed, but 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 create tool with no output schema, it covers the important unknowns: what resources are created, their lifetime bounds, the public-internet side effect, and the billing/capacity accounting. It does not describe the returned run identifier, but the coverage is otherwise strong.

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%, so the description must compensate. It restates the ttl range/default that the schema already documents ('its ttl, default 30m, at most 24h') and adds nothing for the undocumented 'reason' parameter, so it adds little meaning beyond the schema.

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

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

Specific verb + resource ('Start a run of a suite's current version') and it enumerates exactly what is allocated (inbox addresses, callback/mock URLs, route labels). An agent can distinguish this from rig.run.finish, rig.run.cancel and rig.run.get 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?

Provides clear operational context and effectively routes the agent onward with 'Finish the run when done rather than letting it expire' (rig.run.finish). It does not explicitly name the finish/cancel siblings or state when not to start a run, so it stops short of full when/when-not guidance.

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

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

Beyond the annotations (write, idempotent, non-destructive, closed-world), the description discloses concrete side effects: addresses stop accepting immediately and the timeline remains readable, which tells the agent data is preserved rather than purged. It does not mention permission requirements or whether the run must still be active.

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

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

Three short sentences, purpose and outcome front-loaded before the behavioral note and usage trigger. Nothing is padded, though the final 'Use when the test is over' sentence is close to restating the obvious.

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 covers the core effect on addresses and timeline plus the outcome semantics. It leaves the reason parameter, authorization expectations, and the relationship to rig.run.cancel unexplained, which for a state-changing terminal operation is a meaningful gap.

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

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

Schema description coverage is only 33%: outcome carries an inline enum description, while reason and run_id are undocumented. The description repeats the outcome values already in the enum but never explains what 'reason' is for or the expected run_id format, 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 and resource ('End a run') plus the accepted outcomes, so the agent knows it terminates an existing run rather than creating or querying one. It does not, however, differentiate itself from the sibling rig.run.cancel, which is the nearest conceptual alternative.

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

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

'Use when the test is over' gives a minimal usage condition, implying this is the normal terminal operation. It offers no when-not guidance and never mentions rig.run.cancel, so the agent must infer the finish-vs-cancel boundary on its own.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuine value by disclosing the shape of the payload (status, outcome, expiry, resource addresses/URLs), which helps an agent know what it will receive.

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, front-loaded with what the tool returns before the usage hint. Every clause carries information, though the phrasing 'with the address or URL each answers at' is slightly dense.

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 naming the key fields plus the resource addresses. For a single-parameter read tool with full annotation coverage, this is essentially complete, only lacking pagination/edge-case notes.

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 run_id is fully documented in the schema ('A run id from rig.run.create'), so the schema does the heavy lifting. The description adds no additional parameter meaning, 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+resource ('get' one run) and enumerates what a run carries: status, outcome, expiry, and resources with their addresses/URLs. This is clear, though it never explicitly distinguishes itself from siblings like rig.run.create or rig.run.cancel.

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 use case ('Read this for the addresses to configure in the application under test'), which tells the agent when this tool is the right pick. No explicit alternatives or exclusions are named, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is fully covered. The phrase 'exactly as stored' adds a genuine behavioral hint that the definition is returned raw rather than resolved or normalized, but nothing about pagination, errors, or missing-id behavior is given.

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 resource front-loaded and no filler. It is appropriately sized, though 'exactly as stored' is the only clause carrying extra signal.

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 idempotent read with annotations covering safety and a fully described parameter, the description is adequate. However it stops short of describing the returned shape, which matters since there is no output schema.

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

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

Schema description coverage is 100% and the single suite_id parameter is fully documented with its allowed sources (rig.suite.list or rig.suite.upsert). The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('one suite') and adds what is returned ('its current definition'), which distinguishes it from rig.suite.list and rig.suite.upsert by scope. It does not explicitly name those siblings, 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 when-to-use guidance, no mention of alternatives (rig.suite.list, rig.suite.upsert), and no prerequisites. Usage is only implied by the verb 'get' plus the single-id schema.

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, closed-world, non-destructive, so the safety profile is covered. The description adds domain context by defining what a suite is, but says nothing about pagination, ordering, or result size 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?

Two sentences, operation and output fields front-loaded. The trailing definition of 'suite' is educational rather than invocation-critical, but it is compact and aids comprehension.

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 one-optional-parameter read tool with no output schema; the description supplies the returned field list and the semantic definition of a suite, which is sufficient for correct invocation.

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

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

Schema coverage is 100% and the project_id description already explains it comes from rig.project.list. The description's 'project or the organisation' mildly clarifies the unfiltered default, but adds little beyond what the schema 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?

States a specific verb and resource ('Suites in a project or the organisation') and previews the returned fields (id, slug, current version). It clearly reads as a list operation distinct from rig.suite.get/rig.suite.upsert, 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?

The phrase 'in a project or the organisation' implies the two scoping modes but gives no explicit when-to-use, when-not, or pointer to rig.suite.get for a single suite. 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 idempotentHint=true, non-destructive and non-read-only, so the safety profile is covered. The description still adds meaningful behavior: revising stores a new immutable version only when the definition changed, in-flight runs pin their own version, and the operation is free. It does not, however, describe what the call returns or error/validation behavior, so it falls short of 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 sentences with no filler, front-loading the create/revise distinction, then the versioning caveat, then the sequencing and prohibition. Every clause carries information the agent needs.

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

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

For a 5-parameter upsert with a nested definition object and no output schema, the description covers the operation modes, versioning semantics, cost, and sequencing well. The remaining gap is return/identifier behavior (e.g. what suite_id is produced), which the absent output schema leaves unaddressed.

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

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

Schema coverage is only 40%, so the description must compensate and it partly does: it ties project_id and slug to the create path and suite_id to the revise path, which is semantic meaning not present in the schema. It leaves 'name' unexplained and adds no format detail for definition beyond what the schema already documents.

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 suite ... or revise one') and makes the create-vs-revise selection explicit via the parameter that drives each mode (project_id/slug vs suite_id). This is clearly distinguishable from the read-only siblings rig.suite.get and rig.suite.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 concrete when-to-use ('Use before rig.run.create') and an explicit when-not-to-use with the correct alternative ('do not use to change what a running test observes - add resources or faults to the run instead'). The alternative path is named, not merely implied.

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