foundry

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine operational context beyond that: reusing the same chart hits the shared cache, and the scope matches the rendering route. It does not say what certification produces or how failures surface, so it is only a moderate add.

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

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

Three sentences, front-loaded with the action, which is good. But the second sentence loops back to 'the route' in a way that adds words without adding information, and the third sentence mixes the cache note with the fallback pointer, blurring the 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?

The description correctly delegates the enormous chart schema to viz_render's contract, which is sensible. However, on a no-annotations-output tool it never states the return value or the kind of artifact certification yields, and 'certifies the resulting normalized spec' is undefined. Adequate but incomplete for a tool whose whole purpose is producing a certification.

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 the single 'chart' parameter exhaustively. The description adds the one useful pointer, that 'chart' is the viz_render input shape, which is not obvious from the schema alone. Otherwise it repeats schema territory, 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?

States the verb 'certify' and the object 'a chart' and the route ('the same route'), but pivots immediately to referring to itself in the third person ('the route draws it and certifies the resulting normalized spec in the same scope'), which is confusing. It never plainly says what certification means or what the tool returns, and it does not clearly differentiate from viz_render, the tool whose input it consumes.

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

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

Gives one clear routing rule: for arbitrary normalized specs, use local stdio instead. That is an explicit alternative with a condition. But it does not explain when to certify at all versus when to just call viz_render, so the primary use case is left 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, non-destructive and closed-world, so the safety profile is fully covered structurally. The one-sentence description adds essentially nothing behavioral beyond that — no mention of pagination limits, how hidden/internal objects are handled, or default detail behavior, all of which live only in the schema.

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

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

A single sentence with no filler and the core action front-loaded. It is efficient, though it is arguably under-specified rather than truly concise given the tool's eight parameters.

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 is the only place return shape could be summarized, and it says nothing about what a catalog entry contains. The rich per-parameter schema compensates for most of this, but for an eight-parameter listing tool the description is minimally adequate.

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 all eight parameters in detail, including the detail-level enum semantics and the status filter caveat. The description only acknowledges that filters and pagination exist, adding no meaning beyond the structured fields; baseline 3 applies.

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

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

States a specific verb (Read) and resource (the component catalog), so an agent immediately knows it retrieves catalog entries rather than mutating or inspecting anything else. It does not differentiate from any sibling, but no sibling appears to overlap this listing function, so the omission is low-cost.

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?

"with the package's filters and pagination" gestures at how the tool is used but gives no explicit when-to-use guidance, prerequisites, or exclusions. There is no named alternative to route to, and the description leaves the agent to infer that this is the entry point for browsing the catalog.

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 genuinely useful output context — hosted URL, recorded content hash, and reproduction calls — which matters because no output schema exists. It omits any note on auth, rate limits, or what a missing/uncached preview looks like.

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, zero filler, with the lookup action front-loaded and the return payload enumerated afterward. 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?

The description usefully covers return values in the absence of an output schema, and the read-only annotations cover safety. However, two of three parameters (object, context) are entirely undocumented and there is no usage guidance, leaving the agent to guess at valid screen/context combinations.

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 all three parameters are bare enums, so the description must compensate. It only surfaces the framework axis ("React or Vue") and says nothing about the object enum values or the seven context values (detail, list, form, timeline, card, inline, workflow).

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 ("Look up") and resource ("pre-built object screen in React or Vue"), which is concrete enough to distinguish it from generic siblings like object or structuredData_fetch. It stops short of explicitly naming a sibling it differs from, so it lands at clear-but-not-routing.

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

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

There is no when-to-use or when-not-to-use guidance, and no mention of alternatives such as object, viz_render, or catalog_list. The agent must infer the usage context purely from the tool name and description.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds two genuinely useful behavioral facts: the health is 'pinned' (fixed point-in-time) and host folder paths are redacted from the response. It does not describe the health payload itself or the changelog behavior.

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

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

Two short, front-loaded sentences with no filler. The second sentence ('Host folder paths are omitted') is a redaction note that earns its place as output context, though it reads as slightly cryptic without explaining why the paths matter.

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

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

For a zero-required-parameter read tool with complete annotations and schema, the definition is serviceable. However, with no output schema, the description never conveys what 'process health' actually returns, and it is silent on the changelog capability documented in the parameters.

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

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

Schema description coverage is 100% with two optional, well-documented parameters, so the baseline of 3 applies. The description adds nothing about sinceVersion or includeChangelog, but the schema already carries that meaning.

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

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

States a specific verb and resource ('Read the pinned OODS Foundry process health'), which is clearly distinct from the artifact/catalog/preview/registry siblings. It does not explicitly name an alternative, but no sibling overlaps this space, so differentiation is implicit 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?

There is no when-to-use guidance, no prerequisites, and no named alternatives. The agent must infer that this is a diagnostic/status check, which is plausible but left entirely to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that the hosted surface accepts these read actions only, a useful constraint, but it does not disclose pagination, ordering, or what hiddenInternal counts mean behaviorally.

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 core purpose and immediately followed by the read-only constraint. No wasted words.

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

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

For a read-only registry tool with a rich schema and annotations, the description covers the essentials but lacks return format or pagination info. Since no output schema exists, some return behavior could be helpful, though not strictly required for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail, including filters and the includeInternal flag. The description adds no parameter detail, but the schema carries the full burden, making a baseline of 4 appropriate for a single well-documented parameter.

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 specific verbs (list, show) and the resource (object definitions), and clarifies the read-only nature of the hosted surface. It does not explicitly differentiate from siblings like registry_snapshot or catalog_list, but the object-definition scope is reasonably clear.

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

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

No guidance on when to use list vs show beyond the action enum in the schema, nor when this tool is preferred over siblings such as catalog_list or registry_snapshot. The agent must infer usage from the action names alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that - no mention of what the snapshot contains, whether it reflects live vs recorded state, or any loader-issue reporting behavior that the schema description hints at.

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

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

A single front-loaded sentence with zero padding. It is efficient, though the brevity edges toward under-specification rather than disciplined conciseness.

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?

One optional parameter, no output schema, and annotations covering safety mean the structured data carries most of the burden, and the input schema's own description compensates for some of the gap. Still, the description itself gives no sense of what a snapshot read yields, which is a real omission for a data-retrieval tool.

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

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

Schema description coverage is 100% and the single parameter includeInternal is thoroughly documented in the schema itself, so the baseline of 3 applies. The description adds no parameter meaning beyond the structured field.

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

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

States a verb (Read) and resource (pinned registry snapshot), which is more than a tautology, but 'pinned registry snapshot' is never unpacked, so an agent cannot tell what data actually comes back or how it differs from siblings like catalog_list or structuredData_fetch. Adequate but vague on scope.

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 use this tool versus catalog_list, structuredData_fetch, or object, nor any prerequisite or exclusion. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds little beyond restating 'Read' – it does not explain ETag matching, version pinning semantics, or the hiddenInternal behavior, all of which live only in the schema.

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

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

A single tight sentence with no filler. However, it front-loads 'Read' in a way that understates the listing capability, so brevity comes at the cost of precision.

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 6-parameter tool with enum branching, ETag mechanics, and a live-vs-export distinction, the description is far too thin. Though annotations cover safety and the schema covers parameters, the description fails to orient the agent on the versioning/list-versions model that defines this tool's use.

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

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

Schema coverage is 100% and each parameter has its own description, so the schema does the heavy lifting. The tool description adds nothing about parameters like ifNoneMatch, listVersions, or includePayload, leaving the baseline score 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 verb and resources ('Read components, tokens or manifest registry datasets') but is vague on scope and does not distinguish from siblings like catalog_list or registry_snapshot, which an agent might reasonably confuse. The mention of 'including their available versions' hints at listing but is muddled.

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

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

No when-to-use guidance, no mention of alternatives, no indication of when to pick fetch vs catalog_list or registry_snapshot. The one-phrase description leaves selection entirely to the agent's guesswork.

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 non-obvious behavioral context by naming what is returned (source URL and file hash) and by contrasting the hosted surface with the full local package.

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

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

Two tight sentences with the core action front-loaded and no filler. The scope-contrast clause is dense but does real work, so nothing is wasted.

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

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

For a small read-only two-parameter tool with no output schema, the description covers the action, the return payload (source URL, file hash), and the data scope. Only the enum-constrained nature of the required 'name' parameter is left implicit.

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

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

Schema description coverage is 0%, so the description must carry the weight. It partially does: 'input or output schema' maps to the 'kind' enum and 'a tool's' maps to 'name'. But it never explains that 'name' is constrained to a fixed enum list of tool identifiers, nor what the default kind value implies.

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

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

States a specific verb ('Read') and resource ('a tool's shipped input or output schema') plus the returned metadata. It clarifies its own scope (shipped package schemas) but does not explicitly distinguish itself from similarly-named siblings like 'object', 'schema', or 'registry_snapshot'.

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 second sentence implies when this tool's data applies ('Local schemas describe the full package; tools/list describes this narrower hosted surface'), which is useful scope framing. However, it never gives an explicit trigger for choosing this tool or names a sibling to prefer instead, so usage remains inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond them: it enumerates what comes back (real SVG, hashes, accessible output, normalized spec, certification) in the absence of an output schema, and pins the input channel to inline data. It stops short of mentioning failure codes or certification gating.

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 verb. The final clause restating brand/theme enums is mild redundancy against the schema, but the whole thing is tight and wastes little space for a tool of this complexity.

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 19-parameter tool with 13 chart types and no output schema, naming the returned artifacts is a useful addition. But the description omits the overarching mode model (pattern vs chartType+encodings vs rows/intent), which is the single most important routing decision an agent faces; that information lives only in the schema. Adequate but not complete.

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

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

Schema description coverage is 84%, so the schema already documents parameters thoroughly (chartType, geo, hierarchy, encodings, pattern, strictFields all carry rich prose). The description only restates the brand and theme enum values ('brands A/B and light/dark/hc'), adding no semantics beyond the structured fields. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Draw a chart') and the delivery mechanism ('through this site's chart route'), which is concrete enough to distinguish it from sibling tools like artifact_certify. It does not explicitly contrast with siblings, but none of them plausibly collide with rendering a chart.

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?

'Inline data only' gives one real boundary condition (no remote/network data), and the return-content sentence implies it is the rendering step. However, it never says when to reach for this tool versus alternatives such as design_preview, nor does it route between the pattern / chartType / structured-intent modes that dominate the schema.

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