xpex-plugin-factory

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds genuinely new behavioral context beyond those: the output is deterministic and delivered as base64, and no external state changes. It stops short of noting whether compile is expensive or what errors look like for invalid blueprints.

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 output format is stated up front and the non-publishing constraint follows it. 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 correctly supplies the return shape (base64 ZIP) and determinism, and it clarifies the tool's non-mutating nature. The remaining gap is the undocumented blueprint object, which is the one thing an agent most needs 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?

There is one required parameter (a nested object) with 0% schema description coverage, so the description must carry the load. It only says 'valid blueprint' and never characterizes the object's expected fields or structure, leaving the agent to guess at the most important input in the call.

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 (compile), a specific input (valid blueprint) and a specific output form (deterministic ZIP as base64). The phrase 'does not publish the plugin' implicitly distinguishes it from sibling tools like preview_plugin or any publish path, so an agent can place it accurately.

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 via 'a valid blueprint', which hints validation should precede compilation, but never names validate_blueprint or preview_plugin as alternatives or states when to prefer this tool over them. Usage is inferable but not 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?

The annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, covering the safety profile. The description's 'does not authorize payment or generate a kit' adds some domain-specific reassurance, but it largely restates the read-only nature rather than disclosing new behavioral traits.

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 key payload front-loaded and the constraint immediately following. 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 usefully enumerates what is returned (terms, OpenAPI URL, example input), which is exactly what an agent needs to know it can proceed. It is complete for a parameterless discovery 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 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 specific verb ('Return') and the concrete payload (live x402 Agent Kit terms, OpenAPI URL, example input), which is more informative than the title. It does not, however, explicitly distinguish itself from siblings like list_offers or get_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 clause 'Discovery only: does not authorize payment or generate a kit' tells the agent when this tool is appropriate and, importantly, what it will NOT do. No sibling alternative is named, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so 'Read-only' merely repeats structured data. The description adds no behavioral context beyond that — no caching, versioning, or size/shape notes for a zero-parameter introspection call.

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-loading the verb and the returned content. The trailing 'Read-only' is redundant against the annotations, so it is not perfectly lean, but there is no wasted 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 carries the burden of describing what comes back, and it only gestures at 'contract summary and generation endpoints' without saying what fields or endpoints the agent will receive. For a no-arg introspection tool this is adequate but leaves 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?

There are zero parameters and 100% schema coverage, so the baseline is 4. The description does not need to explain inputs, and it correctly avoids inventing any.

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 clear verb+resource: 'Return the factory blueprint contract summary and generation endpoints.' An agent can tell this is a schema/contract introspection tool rather than a mutating sibling like compile_plugin. However, 'factory blueprint contract summary' is jargon that is not unpacked, so the exact purpose remains somewhat opaque.

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

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

No guidance on when to call this versus xpex_factory_list_offers, xpex_factory_get_agent_kit_offer, or validate_blueprint is given. The only orienting phrase is 'Read-only,' which is a safety note rather than a usage condition, leaving the agent to infer the trigger.

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 real value beyond that by clarifying that returning Stripe checkout URLs does not create a checkout or claim payment, preempting a likely agent misconception.

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: the payload is front-loaded in the first, the behavioral caveat in the second. No filler, no redundancy with the name or title.

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

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

For a zero-parameter, no-output-schema list tool, naming the return payload (offers plus checkout URLs) is sufficient for correct invocation. Minor gap: no hint about ordering, pagination, or catalog size, though none is likely needed here.

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 per the rubric; there is nothing further for the description to disambiguate and it correctly avoids inventing parameter detail.

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 ('Return') and resource ('current fixed-price XPeX Plugin Factory service offers and Stripe-hosted checkout URLs'), and is clearly separable from siblings like xpex_factory_get_agent_kit_offer (a single offer) or the compile/preview/validate 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?

Usage context is only implied: the tool is for discovering the catalog of offers before acting. There is no explicit 'use this when...' or an alternative tool named for retrieving individual offers, though the read-only caveat gives a hint about when it is safe to call.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so 'without publishing or mutating external systems' largely restates structured data. The one piece of added value is the 'valid blueprint' precondition, implying validation must precede this call, but return/pagination behavior is not described.

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 states input, output, and the key non-mutation constraint with zero filler. Nothing is wasted or buried.

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

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

With no output schema, the description helpfully identifies the return as 'text artifacts for review,' and annotations cover safety. It is slightly incomplete on blueprint structure and on whether the preview is persisted, but it is adequate for a one-parameter preview 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?

The single 'blueprint' parameter is a nested object with 0% schema description coverage, so the schema conveys no structure. The description only implies the input is a blueprint that must be valid; it does not explain what fields the blueprint object requires or accepts.

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 (compile) and resource (blueprint) producing text artifacts, which is more concrete than the title alone. It implicitly distinguishes itself from xpex_factory_compile_plugin via 'without publishing,' but never names that sibling, so an agent must infer the boundary.

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

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

'For review without publishing' implies the use case (dry-run inspection before publication), and 'a valid blueprint' hints at a validate-first prerequisite. However, no alternative tool is named and there is no explicit when-to-use/when-not statement, leaving routing to be 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds that security policy checks are executed (useful context) but discloses nothing about validation output, failure modes, or how a valid vs invalid blueprint is reported.

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 well-formed sentence that leads with the action and ends with the scoping constraint. Efficient and front-loaded, though brevity here may be a symptom of underspecification rather than discipline.

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 whose sole input is an undocumented nested object and which has no output schema, the description should explain what a blueprint contains and what validation reports back. It leaves both gaps open, so an agent cannot confidently construct or interpret a call.

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

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

There is one required parameter, 'blueprint', whose schema coverage is 0% and whose type is a nested object with no documented shape. The description merely restates the parameter name and adds no structural or content detail, 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 ('Validate a plugin blueprint') plus the scope of checks ('run XPeX security policy checks'). The 'without generating or publishing anything' clause implicitly distinguishes it from generation siblings like compile_plugin, but it never names a 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?

The negative scope ('without generating or publishing anything') implies when this tool is preferred over preview_plugin/compile_plugin, but there is no explicit when-to-use statement or named alternative. Usage is left to inference.

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