Agent Provider Depot

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), and the description adds substantive context beyond them: the output is a dated editorial pick plus a runner-up, a sourced and dated price, and explicit anti-recommendation ('when not to take it'). With no output schema, this is the only place return shape is communicated, though latency, freshness of pricing data, and failure behavior go unmentioned.

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?

Roughly three dense sentences, front-loaded with the decision and its timing, then inputs, then returns, then routing. The nine-item category list is long but does real work by telling the agent whether its domain is covered; only marginal trimming is available.

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 six-parameter, zero-required, read-only recommendation tool with no output schema, the description supplies both the return contract and the sibling routing rule, which is the critical information. Gaps are minor: how 'existing' and 'constraints' influence the pick, and what 'full' expands to, are left entirely to the 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 coverage is 83%, so the schema already documents nearly every parameter, making 3 the baseline. The description reinforces that task text or a jtbd id is the input, but adds nothing about full, existing, maxMonthly, or constraints — notably 'full' and 'existing' remain semantically thin even in the schema.

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

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

States a specific verb and outcome (choose a provider) plus the concrete decision context (before writing integration code) and enumerates the provider categories covered. The final clause distinguishes it from the sibling depot tool, so an agent can route without opening a schema.

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

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

Gives an explicit trigger ('before writing integration code'), an explicit input mode ('send task in words or a jtbd id'), and an explicit exclusion with the alternative named ('For quotes, comparisons and audits use depot'). When-to-use, when-not, and the alternative are all present.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds invocation context such as 'one op per call' and the 'op=help' escape hatch, but it does not describe output behavior, error modes, or rate 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 single dense but front-loaded sentence with no filler, and the op list is compact. Readability suffers from semicolon-separated jargon, but every clause contributes an operation or argument hint.

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?

Given a 17-op dispatch tool with an opaque args object and no output schema, the description provides only terse operation glosses and an op=help pointer. It is minimally adequate for routing if the agent calls help first, but it leaves parameter meaning and sibling differentiation incomplete.

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 burden. It does list argument names per operation (e.g., estimate(jtbd, workload), stack_delta(providers, since)) and points to op=help, which is meaningful compensation, but the argument names themselves are unexplained jargon.

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 identifies the tool as a multi-op lookup surface ('Lookups beyond one pick') and enumerates each operation with a short gloss, so the overall purpose is clear. It does not distinguish this tool from its siblings decide, rescue, or session_brief, and the phrase 'beyond one pick' is somewhat cryptic.

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 explicit guidance on when to use this tool versus its siblings or when not to use it. The op list implies that specific operations exist, but the description never states selection criteria, prerequisites, or alternatives.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds useful behavioral context beyond that: it discloses return content (cause, immediate fix, fallback route) and the no-match branch with checks to run. It does not discuss rate limits or auth, but for a read-only diagnostic tool the remaining gap is minor.

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

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

Two tightly packed sentences with no wasted clauses. The purpose and input expectation are front-loaded, followed immediately by the return behavior and the exclusion.

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?

Despite having no output schema, the description explains both the success return shape and the no-match outcome. It also covers the key input pattern and names the alternative tool, so an agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 100%, so all five parameters are already documented. The description adds only illustrative error values and says to paste 'the exact error and provider id,' which reinforces usage but does not meaningfully expand parameter meaning beyond the schema.

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

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

States a specific verb and resource ('Diagnose a failing third-party API call') and enumerates the error classes it handles (429, 402, 529, insufficient_quota, etc.). It also distinguishes itself from the 'decide' sibling, so an agent can route without opening schemas.

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

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

Gives explicit timing ('before you retry or swap') and an explicit exclusion with the alternative named: 'Not for picking a provider (decide).' This is exactly the when/when-not/alternative guidance the dimension asks for.

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 description's job is to add what they can't: it discloses the three possible statuses (clear|changed|attention), that output is bounded to at most 3 actions each with a source and falsifier, and that a new cursor is returned. It omits auth requirements and any rate/scope limits on how much of the stack can be sent.

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 value proposition and only four sentences, none wasted. The telegraphed clause 'New choice: decide. Live error: rescue.' and 'at most 3 actions (source, falsifier)' take a moment to parse, which is a small cost against otherwise tight 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?

No output schema exists, and the description does describe the return contract (status set, bounded action list with provenance, new cursor), which is the main gap it had to close. For a 6-parameter tool with a nested policies object, the remaining omission is guidance on the policies fields and volume expectations.

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 83%, so the schema already carries parameter meaning; the description adds a real constraint not present there ('never a manifest') and clarifies that the cursor is the caller's last one, tying cursor to the returned value. It says nothing about the nested policies object, though its fields are largely self-describing.

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: a delta report of what changed for the caller's stack since the last call, enumerating the change classes (retired models, price changes, deprecated packages, pick changes). An agent can tell this apart from decide/rescue/depot without opening any schema.

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

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

Gives an explicit trigger ('at session start if your code calls third-party APIs'), an input constraint ('never a manifest'), and routes the two adjacent cases to siblings: 'New choice: decide. Live error: rescue.' Both alternatives and the conditions that select them are named.

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