TrustyCap

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

Annotations already declare the safe/read-only/idempotent profile, and the description adds real behavioral context: it refuses to compose capabilities the platform already supplies, never invents unit prices, prices each meter, and returns an explicit omitted-and-why list. This is meaningful disclosure 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?

The usage cue is front-loaded, which is good, but the prose is dense and run-on, especially the trailing sentence about unit prices and arithmetic. Several clauses could be trimmed without losing information.

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

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

With no output schema, the description carries the burden of describing returns and does so: composed capabilities, real prices, install path, and an omission list. Inputs and refusal behavior are covered; only tie-breaking against sibling tools is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds mode semantics: intent is the human's sentence, capabilities switches to exact-id composition instead of sentence matching, and platform triggers the exclusion rule. That is genuine added meaning over the schema text.

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

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

States a specific verb+resource: take a business description and return the composed capabilities with prices and an install path. It differentiates itself from siblings like list_capabilities and get_launch_kit by describing composition and pricing output, not enumeration.

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 this when your human describes a business" plus two explicit modes (pass platform to exclude what it already supplies; pass capability ids to compose exactly what you picked) give clear invocation context. However it names no sibling alternative or when-not-to-use condition, 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 readOnly/idempotent/non-destructive, so the description goes beyond the safety profile by disclosing the return contents and the crucial behavioral fact that the contract classifies surfaces as customizable/extensible/required/platform_managed/protected, guarding the authorization, metering, proof and payment boundaries. That is meaningful operational context 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?

The usage guidance is front-loaded, but the second sentence is a long run-on with an over-packed parenthetical listing ("new name, brand, audience, pricing, screens, workflow, capability mix") that could be trimmed without losing meaning.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly, enumerating the kit's components and the classification scheme. It is complete enough for an agent to call and use the result, though the absence of field-level detail 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 100% and the single id parameter is documented ("Composition id, e.g. vehicle-finance"), and the description adds nothing about parameter format or valid inputs. Baseline 3 applies when the schema carries the parameter burden.

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 the launch kit / example business) and enumerates the contents: workflow, per-step capabilities, human stops, cost, production checklist, customization contract. Clear what it does, though it does not name or distinguish itself from siblings like get_native_kit or list_launch_kits.

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 this before writing or changing code from an example" gives a clear when-to-use context. No when-not conditions or explicit alternatives are stated, 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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real value by disclosing what is NOT provided ('The packaged source itself is not distributed yet, and no kit carries a price') and that install steps include human-in-the-loop actions in Xcode or a provider console. This tells the agent what to expect and what to warn the user about.

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 manifest contents are front-loaded early, which is good, but the description is an unbroken enumerated list with the instruction 'before touching a native project' repeated at both the start and the end. That repetition costs space without adding meaning, making it longer 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 must carry the return-shape burden, and it does so thoroughly — enumerating file source with hashes and production paths, pinned dependencies, permissions and entitlements with failure modes, the JS interface, immutable config, ordered install steps, and proven constraints. An agent knows what it will receive before calling.

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

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

With a single id parameter at 100% schema coverage, the schema already documents the field including an example ('background-location'). The description adds no format, naming, or lookup guidance beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('One Native Kit's full manifest') and enumerates exactly what that manifest contains, so an agent knows this retrieves one kit's packaged documentation rather than listing kits. It is distinguishable from siblings like trustycap_list_native_kits, though it never names them directly.

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 use context — 'Use this before touching a native project, once a kit has been chosen' — which implies the kit must already be selected (via a sibling listing tool) and that this must be read before modifying a project. It offers no explicit when-not or named alternatives, but the prerequisite condition is well 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context beyond them: it is deterministic, draws only from the published registry and rate card, and explicitly cannot fabricate a capability, composition, or price. It also previews the response contents (matches, reasons, unit cost, actionable build plan).

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

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

The core content is front-loaded and each clause earns its place, but the sentence 'Use this when someone says what they want rather than which capability they want' is repeated verbatim, which is pure redundancy in a short description. That duplication is the main structural defect.

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

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

With no output schema, the description carries the burden of describing returns, and it does so: matched compositions/capabilities, why each matched, unit cost at published prices, and a build plan. Two parameters are fully schema-documented and annotations cover the safety profile, so the definition is nearly self-sufficient; only the launch_kit param and any cost/units caveats go 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 description coverage is 100%, so both parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the meaning of intent (say what the human is trying to build, in their words) but adds no syntax, format, or constraint detail, and the launch_kit parameter is never mentioned in the description at all.

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-plus-resource operation: take a natural-language intent and return matching published compositions/capabilities, the match rationale, unit cost, and a build plan. It also carves out a distinguishing trigger (intent in the user's words vs. naming a capability id), which separates it from the list_* siblings. It stops short of naming which sibling to use instead, so it lands at 4 rather than 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 a clear selection condition: use it when someone describes what they want to build rather than which capability they want, and the launch_kit parameter is positioned as a way to skip the recommendation step. It never names an explicit alternative (route_build, list_capabilities) or a when-not-to-use case, so no exclusion guidance.

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

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

Annotations already indicate readOnlyHint and idempotentHint, so the description doesn't need to restate safety. It adds value by disclosing what the output contains (purpose, constraints, scopes, meters, price), which is essential given the absence of an output schema. It also frames the tool as a pre-check before assuming capabilities exist, offering behavioral context beyond 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 description is long but well-structured: it front-loads the use case, lists illustrative examples, then describes the return, and ends with a clear exclusion. Every sentence contributes to guiding the agent, though the long list of examples could be condensed. It earns a 4 for good organization and purpose-packed 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?

With no output schema, the description must explain return values, and it does thoroughly: what each capability entry includes and how to interpret it. It also covers the family filter implicitly through schema and provides clear usage boundaries. The description is complete for the tool's complexity and lack of 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 only parameter 'family' is clearly documented in the schema. The tool description does not mention the parameter, but with full schema coverage the baseline is 3. No additional meaning is added, but none is needed.

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

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

The description clearly states the tool 'Returns every public capability' and specifies exactly what that includes (purpose, when to choose, what it won't do, scopes, meters, price). It distinguishes itself from siblings by explicitly naming trustycap_list_launch_kits as the alternative for choosing a whole stack, making its 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?

The description gives explicit 'When to use' guidance with concrete examples (files, records, background work, webhooks, etc.), states 'Call this before assuming a capability exists,' and provides a clear exclusion: 'Do not use it to choose a whole stack: call trustycap_list_launch_kits.' This fully covers when and when not to use.

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 disclose readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that examples are starting points, that the builder retains brand/customer/pricing/model ownership, and that the name keeps a legacy identifier. These are useful domain-context additions but not operational behavior like return format or 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?

The description is a series of loosely connected sentences that do not front-load the core action of listing examples. It includes philosophical framing ('An example is a starting point, never a finished product...') and a meta note about the legacy name, which dilute the message. A tool definition should lead with what it does and when to use it.

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

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

For a zero-parameter read-only listing tool with no output schema, the description partially covers what an example contains and adds ownership caveats, but it never explicitly states that the tool returns a list of launch kits or what the list structure looks like. It leaves the agent to infer the return type from the name and title.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. Per the rubric, a zero-parameter tool earns a baseline of 4. The description does not need to add parameter details.

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

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

The description opens by describing the content of an example ('Worked examples of what a kind of business uses...') rather than stating the tool's action of listing. The tool name and title carry the verb, but the description itself never explicitly says it returns a list. It does distinguish from trustycap_compose_kit by calling itself 'optional reading', which helps separate it from that 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 mentions trustycap_compose_kit and says a described business can be composed without one, and that for 'make this production ready' the backend install contract is the default. However, it does not say when to use this tool versus get_launch_kit, list_capabilities, or other siblings. The guidance is more a disclaimer than usable when-to-use instructions.

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 (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description adds genuinely useful behavioral context: each kit is described by a public manifest, packaged source is not distributed yet, and no kit carries a price. That manages expectations about artifact availability beyond what annotations convey.

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

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

The usage trigger 'when the problem is on the device rather than on the server' is stated twice in near-identical wording, which is wasted space in an already long description. The opening 'Native work that is already finished' is also a fragment that adds little. Content is informative but not tightly edited.

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

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

For a zero-parameter, read-only list tool with no output schema, the description supplies nearly everything needed: what a kit is, when to reach for it, and the current limitations (manifests public, source undistributed, no pricing). The only gap is that it never hints at the shape or contents of the returned manifest list.

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 of 4 applies. The description does not need to explain any parameter semantics, and it adds none, which is correct behavior for a parameterless list operation.

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 defines the resource precisely – a Native Kit is 'packaged iOS and Android source with the exact dependency pins, permissions, entitlements, plist keys and protected configuration' – and explicitly contrasts it with a Capability, which lets an agent distinguish it from trustycap_list_capabilities. However, the description never states the verb ('list' or 'returns a collection'), relying on the name/title for that, so it stops short of a fully self-contained purpose statement.

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 is given: use when the app must ship to the App Store/Play Store or the problem is device-side rather than server-side, with concrete examples (background location, native sign-in, store billing, secure storage). It does not name sibling alternatives such as trustycap_get_native_kit for fetching a specific kit or trustycap_list_capabilities, so the agent must infer the 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 a safe, read-only, idempotent, closed-world operation, but the description adds substantial behavioral context beyond them: it discloses the return shape (per-Kit in place / missing-with-consequence / not-visible), explicitly bounds what the scanner will not assert ('cannot see and will not claim about'), and states what the tool refuses to promise (store acceptance, signing keys). This is exactly the extra context annotations cannot carry.

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

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

Usage is front-loaded in the first sentence and the key disclaimer about not promising store acceptance lands near the end where it matters. It runs long across several clauses, but each sentence carries a distinct idea (how to gather inputs, what is returned, what is disclaimed) rather than padding.

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 steps in to describe the return payload (per-Kit status and consequences), which is the main thing an agent needs. For a 10-parameter tool, two parameters (kits, intent) are left with no guidance in either schema or description, a minor gap but not a blocking one.

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 largely restates the same fields the schema already documents (runtime, ios, android, Info.plist keys, manifest, entitlements, min SDK) rather than adding syntax or format meaning. The one genuine addition is the instruction to inspect the project before sending, but 'kits' and 'intent' remain unexplained in both places. Baseline 3 is appropriate given the schema does most of the lifting.

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: inspect a project's native configuration (runtime, ios/android checked-in, Info.plist keys, AndroidManifest permissions, entitlements, min SDK) and report per Native Kit what is in place vs missing. It is distinguishable from siblings like trustycap_get_native_kit, though it never names which sibling to use instead. The purpose is clear but buried behind the usage sentence.

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 an explicit trigger ('when your human wants their application in the App Store or Google Play') and an explicit when-not ('if their creation platform submits to the stores itself, it says so and offers nothing'). It does not name the closest alternative, trustycap_production_readiness, leaving the boundary between the two readiness tools 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, covering the safety profile. The description adds value beyond annotations by stating 'No credential needed' (auth requirement) and 'never inventing a failure for one the scanner did not see' (reliability guarantee). These are behavioral details not present in the schema or annotations.

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

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

The description is front-loaded with the trigger phrase and then enumerates the outputs. It is a single, long sentence but each clause adds substantive information. It could be split into clearer sentences, but it remains readable and focused.

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 tool with no output schema, the description thoroughly explains both inputs and outputs: it lists the output components (current state, implementations, remediation, commands, decline scenarios) and notes the credential requirement. Minor gaps include error handling or specific edge cases, but these are not critical for an agent to call the tool.

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

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

Schema coverage is 100%, so each parameter already has a description. The description references 'requirement id' and 'classification' but does not add additional nuance beyond the schema. The optional 'provider' parameter is not mentioned, but the schema already documents it. The description does not compensate for any gaps given full coverage.

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 action: planning a fix for a production finding from the TrustyCap CLI. It clearly distinguishes itself from siblings by focusing on the remediation pathway rather than discovery or listing. The title and description together convey the exact resource and operation.

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 opens with an explicit trigger: 'Use this when you are holding a finding from... and need to fix it.' This provides clear context for when to invoke the tool. However, it does not mention alternative tools or explicitly state when not to use it, so it lacks the full when-not/alternatives 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, closed-world, so the safety profile is covered. The description still adds real context: no credential required, it must be called before installation, and it discloses the scope of behavioral claims it makes (failure behavior, self-repair, undo, evidence classification). It does not contradict 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?

The trigger and the pre-install ordering are front-loaded, and every sentence carries information about scope, cost, or next steps. It is on the long side with a packed middle sentence enumerating covered topics, but it is not padded.

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

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

With no parameters, no output schema, and annotations covering the safety profile, the description supplies enough to call it correctly: when to use it, that no credential is needed, when to call it relative to installation, and where to go for deeper evidence. It does not describe the shape of the response, but no output schema exists to anchor that.

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

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

The tool takes zero parameters and the schema is empty, so the baseline is 4. Nothing in the description needs to explain parameter syntax, and none is invented.

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 function: answering the decision of whether TrustyCap fits, which option to install, what it replaces, and so on. It is distinguishable from siblings like trustycap_production_plan and trustycap_production_standard, though the opening framing ('Use this when a human asks you...') leans on the trigger rather than a crisp verb+resource statement.

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?

Explicit trigger conditions are given ('make an application production ready', 'give it a real backend', 'get it ready for real customers'), an ordering constraint ('call this before installing anything'), an explicit decline condition ('says what TrustyCap is not for, so you can decline'), and a follow-up routing to trustycap_production_standard.

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. The description adds genuinely useful context beyond them: that no credential is needed and that passing a requirement id narrows the read to one entry. It does not describe the return shape in detail, but the notable operational traits are covered.

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 trigger ('Use this when you need to know...') and free of filler sentences, but the middle sentence is a long appositive-heavy clause packed with several ideas, and the CLI invocation reference is slightly verbose for the value it adds.

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, read-only lookup with no output schema, the description covers what the agent gets back (requirement properties, other satisfying implementations, exact remediate/verify commands), how to scope the read, and that no auth is required. Nothing material is missing to invoke 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% and the single optional parameter is already documented in the schema (including 'omit for the whole standard'). The description restates the read-one/read-all switch, which is mildly reinforcing but adds 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?

The description names a concrete resource — the provider-neutral production requirements an application is scanned against — and ties it to a real artifact (finding ids like TC-PROD-0041 from the productionize CLI). It is clearly distinct from the schema/kits siblings, though it never explicitly contrasts itself with trustycap_production_readiness or trustycap_production_plan, whose names look adjacent.

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 concrete triggers: use it to interpret a production finding, to learn what production requires, or to find remediation/verification commands. It also states the read-one-vs-read-all pattern. There is no explicit when-not or named alternative, which keeps it short of 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds behavioral context beyond that — 'Deterministic and credential free' — which tells the agent the call is cheap, repeatable, and needs no auth setup.

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 when-to-use clause is correctly front-loaded, but the body is a single sprawling sentence enumerating nine output items, making it dense and hard to scan. The content is largely non-redundant, but the structure works against quick 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?

There is no output schema, so the description carries the burden of explaining returns — which it does in detail, covering subtraction of existing capabilities, gaps, task split, and verification calls. Inputs are fully documented in the schema, so the definition is close to complete for an agent 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 coverage is 100%, so the baseline is 3. The description loosely maps to the parameters ('say what built it' → platform/framework, 'what the business needs' → intent, 'anything you found by inspecting the project' → has/findings), which adds some framing, but it never names or disambiguates any parameter and omits `framework` entirely.

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 concrete transformation ('route an existing build to production') and enumerates what the return contains — shortest valid route, what the platform already handles, what's missing, capabilities/kits, task split, verification calls. The verb/resource pair is identifiable, though the purpose is delivered through a long value-prop sentence rather than a crisp statement.

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 when to use it ('when your human already has a working application') and names the alternative with a discriminating condition: 'Call it before trustycap_guide when the human already built something, because this one subtracts what they already have and trustycap_guide does not.' It lacks an explicit when-not branch for greenfield, but the condition implies 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 only declare non-read-only, non-open-world, non-idempotent, non-destructive. The description adds substantial context beyond that: it returns a claim URL but no credential, no API key is issued until an approved human claims it, developer access is by application at a specific URL, and claiming 'attaches everything you already set up and issues the test key.' This is exactly the behavioral disclosure an agent needs for a tool with a human handoff.

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

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

The key instruction is front-loaded well, but the body is prose-heavy and mixes several concerns (platform enumeration, claim flow, application URL) in a long paragraph. The closing sentence 'Those are the steps you cannot do for them' is filler that does not earn its place.

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

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

There is no output schema, so the description correctly explains the return value (a claim URL, not a credential), and it covers the human-approval dependency that gates key issuance. It does not address repeat invocation or state of an existing pending workspace, which matters given the non-idempotent hint.

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 baseline is 3. The description largely restates what the schema already says about name, intent ('in your human's own words'), and platform (listing the same platform values), adding little beyond the structured fields.

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 action and its output: 'Composes a pending workspace for the build: the application, the capability families and the recorded origin, and returns a claim URL.' That is a clear verb+resource with the return value stated. It does not explicitly distinguish itself from siblings like trustycap_compose_kit or trustycap_route_build, 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 an explicit trigger ('the moment you decide TrustyCap fits and before you write any code against it') and clarifies you can 'keep planning, routing and composing with no credential at all.' This is clear when-to-use guidance. It never names which alternative tool handles routing/planning, so the routing value is implied rather than spelled out.

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