mentoring-inquiry-builder

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

Discloses that it is a 'direct booking link' and mentions the discount and claim code, which adds value beyond the readOnlyHint/idempotentHint annotations. No contradictions; the read-only hint aligns with providing a link rather than mutating state.

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 focused sentences: the first states the core function and value, the second gives usage guidance. No wasted words and the most important info is front-loaded.

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 params and no output schema, the description covers purpose, usage timing, and the special handling of claim codes. It is fully sufficient for an agent to select and invoke the tool 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?

With zero parameters, the baseline is 4. The description references 'claim code' and 'booking note' but these are not parameters, so no additional parameter semantics are needed.

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

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

The description clearly states the tool books a free 30-minute intro call with Marian, using a direct booking link. It is distinct from sibling tools which compose, design, get, match, or send offers—none of which handle booking.

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

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

Explicitly says to offer it when the visitor hesitates or wants a human, and adds a special condition for when an offer was already sent. It doesn't explicitly name alternatives, but the context is highly actionable and clear.

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 readOnly/idempotent annotations, the description discloses that the tool echoes the brief with authoritative and AI-channel pricing, applies free-sessions concession for company deals, and instructs the agent to read back and wait for agreement. This adds significant behavioral context without contradicting 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 concise and front-loaded with 'The accumulator — call after every change.' Every sentence serves a purpose, covering the artifact, pricing rule, company concession, and next step without fluff.

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 no output schema and 9 parameters, the description adequately covers the tool's output (echoed brief with prices), the company concession logic, and the required interaction flow (read back, then call send_mentoring_offer on agreement). It could mention prerequisites, but the accumulator pattern makes them implicit.

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 description maps the primary params (audience, role, motivation, focus areas, success definition, chosen package) to the brief components and mentions company-deal specifics. With 56% schema coverage, it adds moderate value, though it doesn't detail every parameter's semantics.

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

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

The description clearly states the tool composes/echoes the full mentoring brief with the authoritative catalog price, positioning it as an accumulator to call after every change. It distinguishes itself from siblings by specifying its role and the follow-up action (calling send_mentoring_offer).

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 instructs to call after every change and never do arithmetic manually, providing clear when-to-use guidance. It also states when to transition to send_mentoring_offer (upon explicit price agreement), giving a concrete usage flow with an alternative 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds substantial behavioral context: it is 'deterministic,' contains 'ONLY what the package carries,' and instructs to 'narrate around it, never add or move a session.' It also clarifies that dates are planning targets, which is not inferable from the schema or annotations. No 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?

The description is concise and front-loaded with the core functionality. Each sentence adds a distinct point: what it is, constraints, date semantics, and when to call. Slightly longer than the ideal two-sentence example, but no wasted 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 tool with no output schema, the description adequately explains the output content (sessions, checkpoint, review) and behavior constraints. It also ties into the engagement lifecycle with the intro call mention. It is complete enough for an agent to use effectively, though some detail on the checkpoint logic is omitted.

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 schema covers 50% with a description for start_date and an enum for offer_id. The description adds meaning by linking offer_id to 'package's cadence metadata' and implies the start_date role in planning targets, but it does not explain the enum values or formatting beyond what the schema already includes. This meets the baseline for 50% coverage.

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

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

The description clearly states a specific verb+resource: 'Deterministic session skeleton computed from the package's cadence metadata' and enumerates what it includes (dated sessions, midpoint checkpoint, closing review). It distinguishes from siblings by describing the output as a fixed skeleton that must not be altered, contrasting with companion tools that create or send other artifacts.

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 provides a clear trigger: 'Call when the visitor asks what the engagement actually looks like.' It also gives important context about the intro call fixing the real schedule, and implies not to use for customization since it says 'never add or move a session.' It does not name explicit alternatives, but the guidance is enough to select appropriately among 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral detail: it returns a specific set of data objects (discount, time promise, materials, qualifying questions, packages) and notes the 16-minute promise. No contradictions 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?

The description is a single dense block but front-loaded with 'START HERE' and efficiently lists the return contents. While it is long, every clause adds specific value, and the structure clearly communicates the tool's role in the workflow. Slightly verbose but not wasteful.

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

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

With no output schema, the description must explain what the tool returns, and it does so thoroughly: discount, time promise, why-Marian material, qualifying questions with answer IDs, and packages with prices. It also provides the workflow context (when to call match_mentoring_focus), making the description complete for a no-parameter 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?

This tool has zero parameters, and schema coverage is 100% (trivially). The description does not need to explain parameters, and adding parameter semantics would be unnecessary. Baseline 4 for no-parameter tools 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 clearly identifies the tool as the starting point for a mentoring inquiry, specifically listing what it returns (discount, time promise, why-Marian, pricing-defense material, qualifying questions, packages). It distinguishes itself from siblings by explicitly positioning itself as 'START HERE' and referencing match_mentoring_focus as the follow-up step.

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 when to use this tool ('START HERE for anyone considering...') and when to move to an alternative ('After the visitor answers audience + role + motivation, call match_mentoring_focus'). This provides clear usage context and a transition to a 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?

Beyond the annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true), the description reveals important runtime behavior: it maps free-text answers to the closest valid id, errors list valid ids for re-asking, and it returns real prices. These details materially help an agent predict tool behavior and handle edge cases, adding value beyond the structured 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 three sentences, each with a distinct purpose: purpose/output, input/error handling, and next steps. It is front-loaded with the most important information and contains no redundant or filler text. Every sentence 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 tool with 2 parameters, no output schema, and clear annotations, the description covers all necessary context: what it returns (suggested focus areas, recommended package, real prices), how input is processed (free-text mapped to ids), error behavior, and the larger workflow context. It is complete enough for an agent to select and invoke the tool correctly without additional guesswork.

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 input schema already has 100% coverage, providing descriptions for both parameters and referencing get_mentoring_options. The description adds crucial meaning by clarifying that parameters accept free-text and are mapped to the closest valid id, and that invalid input triggers a response listing valid ids. This goes beyond the schema's simple 'one of the ids' phrasing, so a 4 is justified.

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

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

The description clearly states the tool's function: 'Resolves role_band + motivation through the same routing the website uses and returns suggested focus areas plus the recommended package with real prices.' This uses a specific verb ('resolves'), identifies the resource (role_band + motivation), and specifies the output. It also distinguishes itself from siblings by referencing website routing and the focus-area/package output, which is unique among the listed 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?

The description provides clear context for when to use the tool by embedding it in a workflow: 'Next: agree focus areas with the visitor, capture their definition of success in their own words, then compose_mentoring_brief.' It also gives error-handling guidance ('on bad input the error lists the valid ids — re-ask rather than guessing'). However, it does not explicitly state when not to use this tool or name alternative tools, so it falls slightly short of a 5.

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

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

Beyond the annotations (readOnly=false, openWorld=true), the description discloses side effects: emails the visitor, notifies Marian, and files the inquiry. It also clearly states the refusal behavior when price_agreed is not true and outlines the post-success actions (claim code, booking link, membership offer, optional ask). 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?

The description is a single dense paragraph but is front-loaded with the core purpose and hard gate. Each segment adds necessary behavioral rules (when to ask, post-success steps), so no sentence is wasted. It could be improved with bullet points but is not overly verbose.

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 15-parameter tool with no output schema, it covers the workflow, the critical gate, and the outcome behavior (emails, notifies, files, returns claim code and booking link). However, it omits semantics for many parameters and does not explicitly state the return format, making it slightly 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 coverage is only 47%, so the description must compensate for the many undocumented parameters. It only adds meaning to name, email, and price_agreed (the gate). It does not explain focus_area_ids, success_definition, role_band, motivation, leaders_count, notes, or other parameters, leaving significant gaps.

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

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

The description clearly states the tool's function: it 'emails the visitor a formal itemized offer with a claim code, notifies Marian, and files the inquiry.' It also explicitly positions itself as 'The ONLY tool that collects contact details,' distinguishing it from siblings like compose_mentoring_brief and book_intro_call.

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?

Provides explicit when-to-use guidance: the 'HARD GATE' requiring price_agreed=true and the instruction to 'Ask for name and email only at this step, never earlier.' It also sets the context as the end of the 16-minute promise, differentiating it from earlier pipeline tools.

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