AgentMart Procurement

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about the authenticated account scope and explicitly rules out side effects like creating sessions or charging, which reinforces safety expectations. It doesn't describe output format, but this is a simple status check with no output 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?

The description is two sentences, front-loading the action and purpose, then adding the read-only clarification. Every sentence earns its place with no redundant or filler 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?

For a simple parameterless tool with no output schema, the description is complete: it states the target account, the specific aspects checked (subscription, payment state, Stripe readiness), and the read-only behavior. An agent has enough information to select and 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?

The tool has zero parameters, so the baseline is 4. There is no parameter meaning to add; the description focuses on what the tool checks rather than inputs, which is appropriate for a parameterless tool.

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 identifies a specific verb and resource: 'Check the authenticated AgentMart account's Growth Pilot subscription, payment state, and Stripe readiness.' It distinguishes this from siblings like create_checkout and create_billing_portal by focusing on read-only status inquiry rather than creating sessions or charges.

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

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

Explicitly states when to use the tool: 'Use for questions about whether billing is active, past due, canceled, or ready.' It also clarifies what it does not do: 'does not create a session or charge anyone.' It stops short of naming alternative sibling tools, but the usage conditions are clearly defined.

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=false and openWorldHint=true, so the tool is known to have external effects. The description adds crucial context: it calls external providers directly and caps each invocation at 30 provider calls, making the scope and safety boundary explicit. It does not detail failure modes, auth, or cost beyond the cap, but the provided behavior is meaningfully transparent.

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 contain all essential information: purpose, user-approval precondition, external calls, and invocation cap. The critical guardrail is stated immediately after the purpose, and there is no filler or redundancy.

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 side-effecting external-call tool with no output schema, the description covers purpose, approval requirement, external nature, and batching bounds. It does not describe the result format, but the purpose statement—collect reliability, quality, latency, and cost evidence—already implies the expected output. Minor gaps in operational detail are acceptable given the other structured schema fields.

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%, so the description does not need to carry the full parameter burden. It adds useful context by explaining the task set is a curated URL set and that invocations are capped at 30 provider calls, which maps to maxCalls. However, it does not clarify repeats or provider selection behavior, and the schema already documents taskIds, providerIds, and confirmExternalCalls.

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

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

The description opens with a specific action—'Benchmark web-extraction vendors'—and names the resource and scope: a curated URL task set collecting reliability, quality, latency, and cost evidence. This clearly distinguishes calibrate from the billing/recommendation siblings, which perform entirely different functions.

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 an explicit precondition: use only after the user explicitly approves a bounded calibration batch. It also warns that the tool calls external providers directly, which informs risk assessment. It does not name specific alternatives or when-not-to-use conditions, but the sibling tools are unrelated and this contextual guidance is clear enough.

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, the description adds valuable behavioral context: the session is short-lived, the customer must explicitly approve, and the operation has no charging or extraction-provider side effects. This meaningfully reduces ambiguity for a tool that could otherwise be confused with a purchase/checkout flow.

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 with no filler. The action and consent condition are front-loaded, and the second sentence adds only the side-effect exclusions that genuinely matter for correct selection. 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 single-boolean tool with annotations and 100% schema coverage, the description covers when to use it, consent requirements, and important non-effects. The only minor gap is not describing what the tool returns, such as a portal URL, but with no output schema and a simple operation this 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 only parameter, confirmCreate, is fully documented in the schema with a const true constraint and a clear description. The tool description's consent condition mirrors the schema's confirmation requirement rather than adding new parameter-level semantics, so the baseline score 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 a specific action and resource: 'Open a short-lived Stripe Billing Portal.' It clearly scopes the tool to explicit customer requests to manage payment methods, invoices, or the AgentMart subscription, and distinguishes it from purchase/execution flows by stating it does not charge or call an extraction provider.

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 a clear, explicit trigger condition: only use when the authenticated customer explicitly asks to manage billing items. It also states exclusions ('does not charge... or call an extraction provider'), which routes non-billing-management requests elsewhere, though it does not explicitly name the alternative sibling tool.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds genuinely useful behavior the annotations do not: no charge occurs unless the customer completes Checkout, and the precondition is explicit user approval. It still omits what is returned (session/redirect URL) and any expiry or idempotency 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 sentences, no filler, with the gating precondition front-loaded before the mechanism. Every clause carries information: trigger, price, mechanism, and the no-charge guarantee.

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 mutation with no output schema, the description covers the trigger, the safety-relevant side effect, and the confirmation gate. The main remaining gap is the return value (a Checkout session URL the caller must surface), which the absence of an output schema leaves undocumented.

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 parameter confirmCreate already has 100% schema description coverage, including the 'only after explicit user approval' condition. The description restates that approval precondition but adds no new syntax or semantics, so the schema does the heavy lifting and the baseline of 3 applies.

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

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

States a specific verb and resource ('Start a secure Stripe Checkout', 'Creates a hosted Checkout session') scoped to a named product at a named price ($149/month AgentMart Growth Pilot). That scope cleanly separates it from the sibling create_billing_portal, which handles an existing subscription rather than starting one.

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 condition: only invoke when the authenticated customer explicitly asks to subscribe to the Growth Pilot. It does not, however, name alternatives (e.g. create_billing_portal for managing an existing plan), so the agent must infer the boundary from the sibling list.

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 discloses several non-obvious behaviors beyond the annotations: it makes external provider calls, records billable usage, enforces account limits, and may fall back to another eligible provider. This is valuable context that annotations alone do not convey, and it does not contradict the annotation flags.

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 compact and front-loads the core purpose in the first sentence, followed by a usage condition and behavioral warnings. The phrase 'Execute, scrape, or extract content' is slightly redundant, but overall the description is efficient and well-organized.

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?

While the high-level behavior is clear, the tool has six parameters, no output schema, and critical extraction-quality controls that the description does not address. An agent would not know how to set markers, quality thresholds, or character minimums correctly, or what a successful result looks like. This is a significant completeness gap for a non-trivial 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 33%, with url and requiredMarkers documented, but minQuality, minCharacters, optionalMarkers, and minRequiredMarkerRatio lack schema descriptions. The tool description does not explain these parameters, their defaults, or how markers and quality thresholds affect extraction, 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?

The description clearly identifies the operation: executing, scraping, or extracting content from a URL via a connected web-extraction provider. This sufficiently distinguishes it from sibling tools like billing_status, quote, and recommend, which handle unrelated billing and recommendation tasks.

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 explicitly states the primary usage condition: 'Use only after the user explicitly asks to run the extraction.' It also warns about external provider calls and billable usage. It does not name alternative extraction tools, but no such sibling is present, so the guidance is clear and practical.

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 and openWorldHint=false, and the description reinforces this ('Read-only and makes no external provider calls'). It also adds valuable output context by naming the explainable recommendation and the cheapest-PAYG counterfactual, which no annotation covers.

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 that front-load the optimization objective before listing factors and return values. Dense but every clause carries 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?

For a tool with no output schema, the description usefully previews the return (recommendation plus counterfactual) and the inputs it weighs. Given the nested candidates array and multiple tunable thresholds, it is nearly complete, missing only the role of the minQuality/minCompletion gates.

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?

Top-level schema coverage is only 25%, so the description must compensate. It names the key decision factors (entitlements, switching costs, reliability, quality, expected demand) that map onto the candidate fields, which helps, but leaves minQuality, minCompletion, and the candidates container semantics 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 ('Optimize') and resource (acquiring a capability) with the scope of purchase paths enumerated. It is clear what the tool does, but it does not distinguish itself from overlapping siblings like 'recommend' and 'quote', which an agent could plausibly reach for instead.

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 explains what the tool computes but gives no explicit when-to-use guidance, no prerequisites, and no exclusions relative to siblings such as recommend, quote, or execute. Usage can only be inferred from the purpose statement.

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 adds useful behavioral context beyond the readOnlyHint annotation by explicitly stating 'it never calls an extraction provider.' It also discloses what the response contains: an account-specific executable-now plan, a broader option, readiness, evidence, assumptions, and warnings. This gives the agent a clear model of side effects and output 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 carry the full value: the purpose and trigger condition are front-loaded, the return contents are summarized, and the read-only guarantee is stated plainly. There is no wasted wording or repetition of schema details.

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 compensates well by summarizing the return shape: an executable-now plan, a broader option, readiness, evidence, assumptions, and warnings. Combined with full schema coverage and clear read-only annotations, an agent has enough context to decide whether to call it. It could be slightly richer about what 'broader option' means, but it is not a material 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 100%, so the baseline of 3 applies. The description does not add parameter-specific meaning beyond the schema; it only indirectly references monthlyExtractions through 'projected monthly volume.' The schema already documents minQuality and minCompletion, so the description adds no extra semantic value for parameters.

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 ('Discover and compare') and a clear resource ('web-extraction procurement options'), then enumerates the exact decision needs it addresses: price, quote, budget, vendor mix, provider allocation, or sourcing plan. This clearly distinguishes it from execution or billing siblings even without naming them.

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 explicitly frames when to use the tool: 'when an agent or user needs a price, quote, budget, vendor mix, provider allocation, or sourcing plan for scraping URLs at projected monthly volume.' It gives clear context and even indicates this is a planning/comparison step rather than an execution step, though it does not name specific alternatives or 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 mark the tool as read-only and non-destructive, and the description reinforces this by explicitly stating 'Read-only: it never calls an extraction provider.' This adds valuable assurance about external side effects. 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 description is compact and front-loaded: the decision purpose comes first, followed by usage context and then a safety-relevant read-only note. Every sentence adds distinct value 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?

The description conveys the core decision among stay, overflow, or upgrade, and the read-only behavior is clear. However, there is no output schema and the description does not explain how parameters like minQuality, minCompletion, or maxRemainingExtractions influence the recommendation, nor does it distinguish this tool from close siblings. This leaves moderate gaps for an agent deciding how to invoke it.

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 by explaining parameters. It only hints at 'remaining URL extractions,' matching the required remainingExtractions field, while minQuality, minCompletion, and maxRemainingExtractions are left unexplained. The description fails to clarify what these thresholds and capacity values mean for the recommendation.

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 decision task — whether to stay on current plans, overflow to another vendor, or upgrade subscriptions — which clearly explains what the tool does. It also anchors the tool in procurement, vendor, capacity, and cost decisions, helping an agent separate it from siblings like usage or quote, though it does not explicitly name those alternatives.

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 clear context: use it for procurement, vendor, capacity, and cost decisions based on current usage and projected remaining URL extractions. It does not, however, state when not to use it or explicitly point to sibling tools such as usage or quote as alternatives, so it falls 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 supply readOnlyHint=true and destructiveHint=false. The description adds useful context that usage is current-month, scoped to the authenticated account, and that calibration calls are excluded, but it does not go deeper into rate limits or response 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?

The description is a single, well-structured sentence with the key resource and time scope front-loaded, followed by a compact list of returned values and a concise exclusion note. Every phrase 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 zero-parameter, read-only usage check, the description covers the main return values and account scope. It does not specify response format or explicitly route to billing_status, but those are minor gaps for a tool this simple.

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 and 100% schema coverage, so the baseline is 4. No parameter-specific semantics are needed, and the description does not try to invent 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 clearly identifies a specific action ('Check') and resource ('current-month web-extraction usage'), and enumerates the returned data. It does not explicitly differentiate itself from siblings like billing_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?

The intended use case (checking current-month usage and remaining limits) is implied clearly, but there is no explicit guidance about when to choose this over billing_status or other siblings, and no exclusions are stated.

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