AI PM Lab

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new context by disclosing that figures come from AI Gateway's live catalog, signaling fresh external data rather than cached figures.

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, front-loaded with the comparison scope before the input convention. Dense but not padded; the enumerated outputs each carry weight, though the run-on clause makes it slightly heavier than necessary.

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?

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. The description covers what is compared and how to supply models, leaving only minor gaps around sibling selection.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, establishing a baseline of 3. The description restates the models-id/provider-name convention from the schema and adds little syntactic or format detail beyond it.

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?

Specific verb (compare) plus resource (models), and it enumerates exactly what is compared: cost per request and per month, prices, context window, output limit, release date and knowledge cutoff. This clearly distinguishes it from siblings like estimate_cost or count_tokens.

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?

States the input style (ids or provider names) and that provider names resolve to newest models, which is useful operational guidance. However, it never states when to reach for this over estimate_cost or price_ai_feature, nor any exclusion criteria, so usage is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond the structured fields: the result is an estimate using OpenAI's cl100k tokenizer and will differ slightly for other model families, which affects how much an agent should trust the number.

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?

One sentence with the core action front-loaded and the accuracy caveat efficiently packed into a parenthetical. 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?

An output schema exists, so return values need no explanation, and the tokenizer caveat closes the main accuracy question. It falls short only on usage context (when this is preferable to estimate_cost) and says nothing about the length limit that the schema imposes.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema, including examples and length bounds. The description adds no syntax or formatting detail beyond that baseline.

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 (count) and resource (tokens in a text), which is immediately actionable. It does not differentiate itself from the related sibling estimate_cost, so an agent must infer the boundary between the two.

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

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

No when-to-use or when-not-to-use guidance is provided. The nearby sibling estimate_cost overlaps in intent, and the description offers nothing to route an agent between them.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and determinism profile is fully covered without the description. The description adds only that the response bundles a definition with related lessons, which is a content-scope detail already implied by the existing output schema. It does not mention behavior on unknown terms or the breadth of the concept set.

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?

One sentence, front-loaded with what the tool returns, followed immediately by the secondary value (related lessons). No filler, no restatement of the title or name.

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?

This is a single-parameter, read-only lookup with an output schema and full annotation coverage, so little additional prose is required. The description is complete enough for correct invocation, with the only minor gap being no guidance on lookup failure or non-matching terms.

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 'term' parameter is documented with examples ('RAG', 'temperature', 'prompt caching'), so the schema carries the parameter burden. The description's parenthetical examples largely duplicate the schema's list and add no new syntax, casing, or matching guidance. Baseline 3 is appropriate when the schema does the heavy 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?

The description clearly states the resource and the content returned: a plain-language definition of an AI concept, accompanied by the lessons that teach it. That 'plus lessons' element separates it from get_lesson and search_lessons, so an agent can place it among siblings. It is a noun phrase rather than a verb-led statement, which slightly softens the purpose signal, but the intent is 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?

Usage is implied rather than stated: the phrase 'with the lessons that teach it' suggests this is a conceptual lookup that also surfaces learning material, distinguishing it from pure lesson retrieval. However, there is no explicit when-to-use rule, no condition selecting it over search_lessons or get_lesson, and no note on what to do for unknown or out-of-scope terms.

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 this read-only, idempotent, non-destructive, closed-world. The description adds the important behavioral detail that the tool 'Returns instructions to follow with the user's text' — i.e., it emits guidance rather than generating the suite itself — which is not in the annotations and materially affects how an agent should use the result. It is consistent with readOnlyHint=true.

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, front-loaded with the action and deliverables, then immediately the return-behavior caveat. Dense and mostly waste-free, with only the light branding phrase 'with AI PM Lab's method' being marginal.

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?

An output schema exists and the description explicitly flags that the output is instructions to follow, so return values don't need elaboration. With one fully documented required-capable parameter and clear annotations, the definition is essentially complete, missing only sibling-relative guidance.

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 parameter carries its own description ('What the AI feature does, who uses it, and what it must never do'), so the schema does the heavy lifting. The description adds only the framing 'planned AI feature' and does not enrich the parameter beyond that, making the baseline 3 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?

Specific verb 'Build' plus resource 'evaluation suite' and an explicit enumeration of deliverables (test cases, graders/judge rubric, pass bars, JSON test set). An agent knows exactly what this produces. It does not, however, name any sibling (e.g., write_acceptance_criteria or review_ai_spec) to disambiguate against a dense set of similar AI‑PM 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?

'for a planned AI feature' implies the usage context (pre‑launch/planning), but there is no explicit when-to-use, when-not, or alternative-tool routing. Usage must be inferred against siblings like write_acceptance_criteria.

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 and destructiveHint=false, so safety is covered. The description still adds real value by disclosing the data source ('AI Gateway's live prices') and the required model-id format, though it says nothing about behavior for unknown ids or the effect of cached_share on results.

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. The cost granularities are front-loaded before the id-format hint, so the agent gets the core capability first.

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 an output schema present, return values need no explanation, and the description states the three cost horizons being computed. It is nearly complete; the only soft spot is that the caching dimension (cached_share) that affects the estimate is not acknowledged.

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

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

Schema description coverage is 100%, so the schema already defines all five parameters in detail, including ranges and semantics. The model-id examples in the description duplicate the schema's own example, and cached_share is never mentioned, so the description adds little beyond the baseline.

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 gives a specific verb-equivalent (estimating cost) and resource (a model call), plus the exact output granularities: per request, per day, per month. It does not name any sibling (e.g. compare_models, price_ai_feature, count_tokens), so the agent must infer how it differs from adjacent 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 is implied by the phrase 'at a given volume', which suggests pre-launch cost planning, but the description never states when to prefer this over siblings like price_ai_feature or compare_models, nor any prerequisites 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered structurally. The description adds that the 'things to try' content derives from recorded runs and that links to the 3D tour and challenge are included, which is modest extra context but not behavioral detail like failure modes or missing-slug 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?

A single sentence, front-loaded with 'A lesson in full', with the content list ordered from substance (decision, key idea) to extras (links, tours, challenge). Dense but every clause names a distinct payload element, so little is wasted.

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

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

With an output schema present, enumerating the returned contents in the description is largely duplicative, and the description thus spends its budget restating the shape rather than covering the gaps that remain (verb, when-to-use, behavior on an unknown slug). Adequate for calling the tool, but not compensatory.

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?

Only one parameter exists and schema description coverage is 100%: the schema documents the slug and enumerates all 18 valid values, and even notes its provenance from search_lessons. The description adds nothing about the parameter, so the 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 specific resource (an AI PM Lab lesson) and enumerates its parts — product decision, key idea, things to try, takeaways, questions, links — so an agent knows what 'a lesson' contains. However, the verb is only implicit ('A lesson in full' rather than 'retrieve the full lesson by slug') and it never names the sibling it differs from, search_lessons, which is the natural alternative.

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?

Nothing says when to call this versus search_lessons (discovery) or define_term/quiz_me (reinforcement). The only routing hint lives in the schema's slug description ('from search_lessons'), not in the description text, and there are no exclusions or prerequisites 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered without description help. The description adds useful context about what the returned data represents (recorded runs, leaderboards), but says nothing about pagination, ordering, or whether the list is exhaustive.

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 short sentence with no filler, and the definition of what a challenge is is front-loaded parenthetically. It reads as a noun fragment rather than a full statement of action, which slightly weakens the framing but wastes no words.

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

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

For a zero-parameter read-only listing with an output schema that already documents the return shape, the description supplies the one thing the schema cannot: what a 'challenge' actually is. Only the routing against sibling list tools is missing.

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 clarify; baseline 4 applies. No parameter-level ambiguity is introduced.

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 the resource (challenges = games scored from real recorded runs with leaderboards) and says the listing includes what each challenge asks the agent to do, so the effect of the call is clear. It does not, however, distinguish itself from the nearest sibling (list_experiments), which an agent would need to disambiguate 'list' 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?

There is no explicit when-to-use statement, no prerequisites, and no mention of alternatives such as list_experiments or replay_experiment. Usage is only weakly implied by the fact that it is a listing tool with no parameters.

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 reads, so the safety profile is covered. The description adds useful domain context — what an experiment record contains ('which defences or settings were on') — but does not clarify list size, ordering, or that nothing is mutated.

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 padding, and the resource definition comes first. The second sentence, however, is off-purpose for a listing tool and points at the behaviour of a different tool, which costs 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?

An output schema exists so return values need no explanation, and the single required parameter is fully covered by the schema. What is missing is the minimal statement that this retrieves a collection for the given page — and the stray replay instruction can mislead an agent about what calling this tool does.

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 enum is fully documented in the schema, so the baseline is 3. The description loosely mirrors the dual page/lesson nature of the single `page` parameter but adds no constraint or format detail 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?

The description names the resource precisely (recorded runs on a specific 3D page or lesson, each with its setup), so the agent knows what kind of object is involved. However it never states the verb — it is a noun phrase plus 'Replay one', leaving 'list' to be inferred from the tool name, and it spends its last sentence describing an action that belongs to the sibling replay_experiment.

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 when-to-use statement and no named alternative, even though replay_experiment is an obvious sibling for the 'see what happened' path. The trailing sentence gestures at a next step but never says which tool performs it or when to pick this one over searching lessons or challenges.

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. The description adds real behavioral content on top: what the output is (exit criteria, tests and checks per phase), its provenance (findings from recorded real runs), and notably that it 'Returns instructions to follow with the user's text' rather than data. That return-shape disclosure is the useful addition; pagination/format specifics are left to the 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?

Opens with the core noun phrase 'A phased roadmap...', so the payload is front-loaded. It is dense but every clause carries information (phase names, exit criteria, provenance). The long colon-list in the middle sentence costs some readability, keeping it from a 5.

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 an output schema present, the description need not detail return values, and it still usefully notes that the output is followable instructions. Combined with the phase breakdown and provenance, an agent has enough to call it correctly; only sibling routing is missing.

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 'feature' param is fully documented in the schema, so baseline 3 applies. The description broadly frames the subject matter but adds no format, length, or content-shaping guidance beyond what the schema already states.

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?

Names the resource (an AI feature) and what it produces: a phased roadmap running from current state to launch and first month live, with an explicit phase list. That is a specific verb+resource. It stops short of differentiating itself from siblings like review_launch_readiness or prep_planning_meeting, so 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?

The usage context is implied by 'from where an AI feature is today to launch', so an agent can infer 'use this when planning a launch'. But there is no explicit when-to-use/when-not, no prerequisites, and no alternative tools named despite several closely related siblings.

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 behavior, so safety is covered. The description adds genuinely useful non-obvious context: the tool returns instructions to follow rather than a direct answer, which shapes how the agent should consume and act on the result. It does not cover edge cases or what happens with empty input, keeping it below a 5.

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 first sentence front-loads the content of the result, though the trailing 'Returns instructions to follow with the user's text' is slightly ambiguous and reads as an afterthought.

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 tool with an output schema and full annotation coverage, the description is adequate: return values need not be explained and safety is handled. The notable gap is situational framing – when this should be chosen over sibling planning tools – which leaves the agent to guess placement in a workflow.

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 parameter at 100% schema coverage, the schema already documents 'feature' as a few sentences about the AI feature. The description's phrase 'a planned AI feature' and 'the user's text' loosely align with that parameter but add no syntax, length, 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 specific artifact it produces – the questions a PM should ask engineers about a planned AI feature, with rationale and example good answers – which is more concrete than the name alone. It stops short of distinguishing itself from planning-adjacent siblings such as plan_ai_launch or review_ai_spec, so it is clear but not sibling-routing.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative among the many overlapping planning/review siblings. The agent must infer the moment to call this from the title alone.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is low. The description adds genuinely non-obvious behavior: it doesn't compute anything itself but 'Returns instructions to follow with the user's text,' telling the agent to expect a procedure to execute rather than a finished answer. No contradiction with 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?

A single dense sentence that correctly front-loads the core purpose before the enumerated sub-topics, followed by one short sentence on the return shape. Every clause earns its place, though the middle list is somewhat packed.

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?

An output schema exists, so return values need not be explained; the description still helpfully notes the output is a set of instructions. It says nothing about limits or caveats for the 50k-character input, but for a single-parameter, read-only reasoning tool this is essentially complete.

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

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

One parameter with 100% schema description coverage, which already explains the expected input (feature description, model, usage, current pricing). The description adds nothing about the parameter's content or the sizable 50,000-character allowance. Baseline 3 applies when the schema does the heavy 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?

The description opens with a specific verb+resource ('Work out an AI feature's unit economics and pricing') and enumerates the deliverables: per-request/per-user costs, levers, pricing options with margins, guardrails, assumptions. It is clearly distinct from adjacent tools like estimate_cost or plan_ai_launch by naming pricing/margins as its output, though it never explicitly contrasts itself with those siblings.

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 is only implied: the agent can infer this applies when a user wants pricing for an AI feature, but there is no statement of when to pick this over estimate_cost (cost estimation) or plan_ai_launch, and no prerequisites or exclusions. Adequate but leaves selection 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 only declare the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false, idempotentHint=false). The description adds genuinely useful behavior not in the structured data: the answer is deliberately withheld on the first call, a second call with round+answer performs the marking and returns cohort stats plus the next round. It could say more about whether the marking call persists state, which leaves a mild gap.

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 first sentence front-loads the game modes before the second sentence explains the two-phase return behavior, and no sentence is wasted. It is a touch dense because the mode list and the call flow are packed together, but the structure is sound.

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 an output schema present, the description need not detail return values, and it still covers the key non-obvious behavior: the answer is withheld, a second call marks it and returns the next round plus community results. That is complete enough for an agent to drive the tool across calls.

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 schema already documents game, round, and answer. The description explains the friendly names of the enum game modes and ties 'round id' and 'the user's choice' to their parameters, but adds only marginal meaning beyond the schema, so the 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 states a specific resource (a quiz round from AI PM Lab's challenges) and enumerates the three modes (Call It, Spot the Failure, Which Wins?), clarifying exactly what this tool produces. It is distinguishable from siblings like list_challenges and get_lesson, which merely enumerate or teach rather than deliver an interactive round.

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 strong procedural guidance for both phases: the first call returns a question without its answer, and a second call with the round id and choice marks the answer, shows community results, and fetches the next round. It does not name when-not-to-use it or point to alternative tools, so it stops short of the explicit alternatives a 5 would require.

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 read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds value by enumerating what the record contains (setup, each step, result, the model's reply, a run-on-site link), which is real context beyond the annotations. It does not clarify pagination or output size 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?

A single front-loaded sentence with no filler; the enumeration of returned content earns its place. It could be tightened slightly, but there is no wasted text.

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?

An output schema exists, so the description need not detail return values, and it correctly focuses on what the record represents plus the link to run it live. Combined with full schema coverage and read-only annotations, this is nearly complete for a two-param read 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%, and both params are self-documenting ('run's number from list_experiments', page enum of 3D pages vs lesson slugs). The description adds no syntax or format detail beyond the schema, so the 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 makes clear this surfaces the full detail of a single recorded run (setup, steps, result, model reply, link), which is more specific than the bare name 'replay'. It does not explicitly name the sibling it complements (list_experiments), though 'one recorded real run' implicitly contrasts with a list 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?

Usage is implied rather than stated: the parenthetical examples (prompt injection, hallucinated answers) suggest when this is useful, and the 'run' param ties it to list_experiments. However, there is no explicit when-to-use/when-not guidance or named alternative, so it stays at minimum-viable.

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 the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description adds a genuinely useful behavioral fact: it "returns instructions to follow with the user's text" rather than performing the review itself, which explains the readOnlyHint. It stops short of noting any output size or length 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?

Two sentences, front-loaded with what the review covers and followed by the key behavioral note about returned instructions. No wasted words, though the mid-sentence enumeration is dense.

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 annotations covering safety, full schema coverage on the one parameter, and an output schema present, the description need only carry the concept and the instruction-returning behavior, both of which it does. Only explicit sibling routing is missing.

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 "incident" parameter is fully documented as "what the feature does, what went wrong, and what's known so far." The description's list of failure dimensions adds framing but does not extend the parameter's meaning 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?

States a specific verb and resource: "blameless post-incident review for an AI feature," and enumerates the dimensions the review covers (input, retrieval, prompt, model, tools, output checks). It implicitly separates itself from review_ai_spec and review_launch_readiness by being incident-scoped, but never names those alternatives explicitly.

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?

"Post-incident" implies the trigger condition (an incident has occurred), which is reasonable implied usage. However, there is no explicit when-to-use guidance, no when-not-to-use, and no routing to sibling review_ai_spec/review_launch_readiness, leaving the agent to infer.

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 read-only, idempotent, non-destructive, closed-world behavior. The description goes further by disclosing output traits beyond the annotations: gaps link to lessons and the tool 'returns instructions to follow with the user's text,' which tells the agent how to act on the result. No annotation contradiction.

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, front-loaded with the verb and the primary resource. The long middle checklist is dense but every item earns its place by defining review scope; 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?

Output schema exists, so return values need not be spelled out, and the single parameter's schema coverage is complete. The description supplies the review dimensions and the safety profile is carried by annotations, leaving only explicit when-to-use guidance as a 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?

Only one parameter ('spec') with 100% schema description coverage, so the schema already documents it fully. The description restates the input as 'an AI feature spec or PRD' but adds no format, size, or content requirements beyond what the schema provides.

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 ('Check') and resource ('AI feature spec or PRD') and enumerates the exact dimensions reviewed, so the agent knows the scope precisely. It does not distinguish itself from siblings like review_launch_readiness or review_ai_incident, keeping it 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?

Usage is only implied by 'Check an AI feature spec or PRD against what AI PM Lab teaches.' There is no explicit when-to-use statement, no when-not-to-use, and no pointer to a sibling for adjacent review tasks (launch readiness, incidents).

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 the safe, read-only, idempotent, closed-world profile, so the description is free to add the useful behavior: the output is a per-dimension ready/at-risk/missing verdict plus blockers and a launch-day watch list, and it 'returns instructions to follow with the user's text.' That last clause tells the agent this yields guidance to act on rather than a stored artifact — context not available from 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?

Two sentences, front-loaded with the verdict and the dimensions assessed, with the return behavior held to the end. The long enumeration of lifecycle areas is dense but each item earns its place by telling the agent what the review covers.

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 an output schema present, the description need not spell out the return shape, yet it still summarizes it usefully. Combined with the one-parameter schema, the agent has everything needed to invoke it; only the relative positioning against sibling review/plan 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?

There is a single parameter with 100% schema description coverage, so the schema already fully documents 'plan' (feature, what was tested, launch plan). The description adds nothing parameter-specific beyond implying the input is a launch plan; baseline 3 is correct.

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 'go/no-go review' of an AI feature's launch plan — and enumerates the exact dimensions checked (evals, grounding, attacks, cost, latency, etc.), so the agent can tell it apart from plan_ai_launch. It stops short of explicitly distinguishing itself from the other review_* siblings (review_ai_spec, review_ai_incident).

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 is implied by the framing: you run it on a launch plan to decide go or no-go. There is no explicit statement of when not to use it, no prerequisites, and no named alternative such as plan_ai_launch for the authoring step.

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. The description adds that results are relevance-ranked ('best matches') with 'key idea and link', which is useful context, but no pagination or result-count limits are disclosed.

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, front-loaded with the action and resource, then the return shape. No wasted words and the topic examples are compact and useful.

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?

An output schema exists, so the description need not detail return values, and annotations cover the safety profile. It is nearly complete for a simple one-param read tool; the only gap is not distinguishing itself from the get_lesson sibling.

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 'query' param is fully documented in the schema with an example. The description's topic examples add marginal framing but no syntax or format detail beyond what the schema already provides, so the 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?

Clear specific verb ('Find') plus resource ('AI PM Lab lessons') with concrete topic examples (RAG, evals, agents). An agent can tell this is a topic-based search tool. However it does not differentiate itself from the close sibling get_lesson, which likely fetches a specific lesson.

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 is only implied by 'on a topic'; there is no explicit when-to-use vs when-not, and crucially no routing to the sibling get_lesson for retrieving a single known lesson. The 'best matches' phrasing hints at ranked exploration but doesn't state the condition clearly.

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 carry the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds non-obvious context: the tool 'Returns instructions to follow with the user's text', i.e. it does not itself emit the final artifact. That is real behavioral value beyond the annotations, though it stops short of describing limits or formatting of the returned instructions.

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?

One dense but front-loaded sentence: the deliverable leads, the content list follows, and the return behavior closes it. No filler, though the long comma-separated inventory pushes it toward list-like packing rather than crisp prose.

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 an output schema present the description needn't explain return values, and it still sketches what the criteria will contain plus the note that it returns follow-up instructions. For a single-parameter generation tool this is close to complete; only explicit routing against sibling review/design tools is missing.

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 single 'feature' parameter is already fully documented in the schema, and the description's 'with the user's text' only loosely maps to it. Baseline 3 applies when the schema does the heavy 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 concrete deliverable (acceptance criteria for an AI feature/user story) and enumerates its contents — Given/When/Then, pass bars, safety criteria, latency/cost budgets, example test cases — so the agent knows exactly what artifact this produces. It does not name or distinguish itself from nearby siblings like design_eval_suite or review_ai_spec, which keeps it below 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?

Usage is implied rather than stated: the criteria are 'ready to paste into a ticket' and require 'the user's text', which frames the context, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as review_ai_spec for critiquing an existing spec. Minimum viable but with clear gaps.

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