mentoring-inquiry-builder

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

Goes well beyond the annotations: discloses the refusal condition and fallback behavior, the company-paid flow (PO collected after session 1, never before booking), and that a claim code is needed to auto-match the booking. readOnlyHint/idempotentHint are consistent with a tool that returns a link rather than mutating state, so 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?

Dense but front-loaded — the main action and return value come first, then the refusal rule and routing. Every sentence carries operational information, though the run-on parenthetical structure is slightly heavy.

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 compensates by stating the return value (booking link plus payment terms). Combined with exhaustive usage and refusal guidance for a 6-parameter workflow tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains why claim_code matters (auto-matching the inquiry with no manual step) and that free_sessions_requested reroutes the call to the intro. That is decision-relevant semantics beyond the schema text.

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 ('booking the first regular session') and what it returns ('the direct booking link for the paid 60-minute first session, plus the payment terms'). It explicitly differentiates itself from siblings by naming send_mentoring_offer (predecessor) and book_intro_call (the alternative when the visitor is hesitant).

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 precise when-to-use ('call it right after send_mentoring_offer succeeds'), when-it-refuses (deals with a free-sessions concession, monthly package, Mentor in Residence), what to do on refusal ('offer the intro, do not argue'), and the alternative path for hesitant visitors (book_intro_call). Covers both positive and negative selection 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=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds non-annotation context: that the call is 'never a downgrade,' that booking is NOT a condition of the channel rate, and that offer_id shapes the pricing language in the CTA. It does not discuss auth or rate limits, but for a read-only link generator this is appropriately rich.

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?

It is front-loaded with 'THE FALLBACK' and the core action sentence comes immediately, which is good structure. The list of trigger scenarios is somewhat verbose and partially overlapping ('on hesitation' vs. 'to anyone who wants to talk before paying'), costing some efficiency but not readability.

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 only 2 optional parameters, full schema coverage, and annotations carrying the safety profile, the description covers selection, routing, and even the return behavior ('A direct booking link' whose CTA echoes the package price). It is essentially complete; only minor duplication keeps it from a 5.

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 is 3. The description's note to 'Pass offer_id if one has been chosen so the pricing language is correct' adds the rationale and the condition for passing it, but largely restates what the schema already documents. No syntax or format details are added beyond that.

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+resource: 'A direct booking link for the free 30-minute intro with Marian.' It also explicitly distinguishes itself from its closest sibling, naming book_first_session as the 'main ending' while positioning this tool as 'THE FALLBACK.' An agent can route correctly without opening either 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?

It enumerates precise trigger conditions ('on hesitation, on a price objection, when the visitor cannot name their problem, after an error, and to anyone who wants to talk before paying') and an explicit when-not: for a visitor who has already agreed the price on an eligible package, use book_first_session instead. It even gives the reasoning for the exclusion.

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 read-only/idempotent safety, but the description adds material behavior: the few-second webhook write latency, the two-field return (pipeline stage, whether the paid first session is on the board), and a retry/escalation policy. This is context the annotations cannot express.

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 sentences, front-loaded with the core purpose, then the trigger condition, then the failure-handling rule. No filler; each sentence carries distinct, load-bearing information.

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, yet the description explains what comes back and how to interpret and act on each outcome, including the timing caveat and the honest-failure fallback. An agent has everything needed to call and use the result.

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 both parameters (email, context) are already documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so 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: it confirms from the CRM (not from the visitor's claim) whether a booking landed. The framing 'a booking is only real once Reclaim's webhook has written it' distinguishes this verification tool from the booking siblings without ambiguity.

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 when to call it ('after handing over a booking link and the visitor says they have booked') and what to do on a negative result: wait and re-check once, and if still absent, escalate to Marian rather than claim success. This is fully actionable 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 only cover the safety profile (readOnly/idempotent/non-destructive); the description adds real behavioral context on top: the price is authoritative and the agent must never compute it, the AI-channel figure is supplied, and the free-sessions concession is conditionally reported for company deals. None of this is derivable from the structured fields.

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?

Four tight sentences, front-loaded with the tool's role as accumulator, then what it returns, then the conditional concession logic, then the handoff rule. No filler and no restatement of the title.

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

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

There is no output schema, so the description carries the return burden and does so — it names exactly what is echoed back and what price data accompanies it. Combined with the safety annotations and full schema coverage, an agent has everything needed to call and consume 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?

Schema coverage is 100%, so the schema already documents all ten parameters including the enumerated answer ids. The description only restates the field list it echoes; it adds no syntax, format, or default guidance beyond what the schema 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?

States a specific verb and resource ('compose/echo the full structured brief') and enumerates the fields it carries plus the authoritative price. It also distinguishes itself from the sibling it hands off to (send_mentoring_offer) and from the option-listing tools, so an agent can place it without opening the 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?

Explicit timing ('call after every change') and an explicit downstream condition ('when they explicitly agree on the price, call send_mentoring_offer with price_agreed true'). It also gives the conversational protocol (read the brief back to the visitor) that gates the next call.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the key behavioral constraints: it is deterministic, it contains ONLY what the package carries, you must never add or move a session, and dates are planning targets that the intro call later fixes. Those are exactly the behavioral traits an agent needs and that annotations cannot convey.

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 deterministic-skeleton purpose, and every clause earns its place by constraining behaviour. It is dense with parentheticals and runs long for a single paragraph, but there is 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?

With no output schema, the description carries the burden of describing the return, and it does so adequately by enumerating the session themes (diagnostic, focus areas, mid-point checkpoint, closing review). It could be clearer on exact return shape, but an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: focus_area_ids become the planned themes of focus sessions and leave them 'open' when absent, and leaders_count changes only the allocation note, never the schedule. That maps parameter effects to output consequences rather than restating 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?

It names a specific verb+resource: 'Deterministic session skeleton computed from the package's cadence metadata' producing 'dated sessions, each with its planned theme.' This is clearly distinct from the booking/compose siblings, though no sibling is named to sharpen the boundary.

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

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

It gives an explicit trigger — 'Call when the visitor asks what the engagement actually looks like' — and frames the output as a planning artifact rather than a booking. No alternative tool is named for the adjacent cases (e.g. when to book versus plan), so it stops short of full when/when-not 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real context beyond them: the output is static data, the pricing is identical to the website with no discount path, the sub-10-minute offer promise, and that the optional context parameter is recorded only as intent and "never changes the answer."

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 highest-value signal ("START HERE") and ends with the explicit next action, so the structure is sound. It is dense and slightly promotional ("no discount through any door"), with a few clauses that could be trimmed without losing instruction value.

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?

There is no output schema, so the description must carry the return-value burden — and it does, enumerating every returned artifact including qualifying questions and packages. Combined with annotations covering side effects and a fully documented single parameter, an agent has everything needed to call this 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?

One optional parameter with 100% schema description coverage, so the schema already explains it fully; baseline 3 applies. The description only corroborates the schema by noting the intent-recording behavior, adding no format or syntax 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?

Names a concrete scope — 1:1 engineering-leadership mentoring with a specific practitioner — and enumerates exactly what the call returns (pitch, no-discount pricing stance, qualifying questions with valid answer ids, packages with real prices). An agent can tell this apart from booking or matching siblings without opening the 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?

"START HERE for anyone considering..." gives a clear entry condition, and "After the visitor answers audience + role + motivation, call match_mentoring_focus" names the explicit next step in the flow. It does not, however, distinguish itself from the sibling get_started, which is also an entry-point tool, nor say when to skip straight to booking.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds behavioral context: that it returns the full menu when no arguments are provided, and that it can serve as a liveness check. This goes beyond the structured annotations without contradicting them.

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 with the primary use case front-loaded. It is efficient but includes some redundancy with the schema (e.g., 'pass it as context'). Still, it is appropriately sized and structured for the tool's simplicity.

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 one optional parameter and no output schema, the description fully covers when to use it, how to invoke it (with or without context), and the expected outcome (returns the full menu). No critical information is missing for an agent to call it correctly.

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

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

Schema description coverage is 100% for the single 'context' parameter, which already explains its purpose (goal description, greeting, or omission). The description restates the usage ('pass it as context, or send no arguments') but adds no new semantic details beyond the schema. Baseline 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 clearly states a dual purpose: discovering additional tools for specialized capabilities, and handling greetings/liveness pings. It differentiates itself from the mentoring-specific siblings by positioning itself as the fallback/general tool, with a specific verb ('Check for') and resource ('additional 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 explicitly specifies when to use it: 'whenever your task might benefit from specialized capabilities, even if existing tools could work as a fallback' and for greetings/liveness/general messages. It implicitly tells when not to use it by noting it's for messages 'too general to match a specific tool', which guides the agent to prefer specific siblings when applicable.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false. Beyond that, the description discloses what the tool returns (full menu of real questions mapped to tool names) and the behavioral side effect of the context parameter (recorded as intent, never changes the answer). That is meaningful additional transparency for a no-required-parameter help tool.

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 tightly constructed sentences: first the use cases, then what it returns, then the alternative tool. Nothing is wasted, and the most important routing information 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 read-only, zero-required-parameter help tool whose annotations already cover safety, the definition supplies purpose, usage triggers, the alternative tool, return content, and the side effect of the optional parameter. An agent has everything needed to call it correctly; the absence of an output schema is mitigated by the description of what the menu contains.

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 single optional 'context' parameter is already fully documented in the schema. The tool description does not mention the parameter or add format/syntax guidance beyond what the schema provides, so the baseline 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 states a specific verb and resource: it is a greeting/liveness/help tool that returns a menu of real questions mapped to tool names. It explicitly distinguishes itself from the sibling get_mentoring_options by telling mentoring-seekers to skip this tool. An agent can immediately understand this is the general fallback/help tool.

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 explicit when-to-use triggers (greeting, connectivity test, 'what can you do', any message too general to match a specific tool) and an explicit when-not/alternative (for someone actually considering mentoring, skip to get_mentoring_options). No inference is required.

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 disclose readOnly/idempotent/non-destructive safety, and the description adds genuinely new behavior: the routing mirrors the website, the response includes real prices, and invalid input yields an error listing valid ids. That error-contract detail is valuable and not derivable from the annotations, though return format/pagination is left unstated.

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 dense sentences that are front-loaded with the core purpose and end with actionable next steps; every sentence contributes. Slightly tight-packed with mixed concerns (purpose, error handling, next steps) rather than perfectly scannable, but 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?

Even without an output schema, the description conveys what is returned (suggested focus areas + recommended package with real prices) and how failures behave. Combined with the read-only annotations, an agent has everything needed to call it correctly and act on the result.

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 baseline is 3; the description earns above that by adding meaning the schema doesn't carry — free-text answers must be mapped to the closest valid id, and bad values surface via an error with valid ids. It reinforces the audience/leaders_count routing effect already noted 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+resource ('Resolves role_band + motivation') and the concrete outputs (suggested focus areas plus the recommended package with real prices), so an agent knows exactly what it does without opening the schema. It also implies differentiation from siblings by naming the routing behavior and pointing to compose_mentoring_brief as the successor 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?

Gives clear sequencing context ('Next: agree focus areas ... then compose_mentoring_brief') and explicit handling for bad input ('re-ask rather than guessing'). It stops short of naming when NOT to use this tool or directly contrasting it with design_mentoring_program, so it's clear context but not full when/when-not/alternatives coverage.

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 write (readOnlyHint=false), non-idempotent, open-world, non-destructive. Beyond that, the description adds real behavior: the tool refuses unless price_agreed is true, sends an email, notifies Marian, files the inquiry, and warns that optional answers are 'never invented'. It does not address double-send/idempotency risk, which would have earned 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?

Front-loaded with purpose, the contact-collection scope, and the hard gate before the post-success scripting, so the critical parts come first. It reads as a dense run-on block, and the closing ELC-gift/one-ask sentence is arguably tangential, but nearly every clause carries operational instruction.

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 28-parameter, terminal-step write tool with no output schema, the description covers the gate, the data to pass in, and the expected follow-up (share claim code + booking link). It does not describe the returned payload beyond implying the claim code, nor how failures other than the price gate surface, leaving a small 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?

With 93% schema description coverage the baseline is 3; the description adds genuine meaning by grouping the twelve onboarding answers as pass-through data that must be gathered and 'never invented', and by pinning name/email collection to this step only. It still doesn't clarify the required offer_id/audience/role_band/motivation fields, so it is above baseline but not comprehensive.

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 verb set and outcome: 'emails the visitor a formal itemized offer with a claim code, notifies Marian, and files the inquiry', plus the positioning cue 'the ONLY tool that collects contact details'. That scope claim plus the title ('list prices, no discount') distinguishes it from book_first_session and compose_mentoring_brief 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 a clear placement rule ('the end of the 10-minute promise', 'Ask for name and email only at this step, never earlier') and a named prerequisite ('the exact price from compose_mentoring_brief'). It stops short of naming explicit alternatives or exclusions beyond the hard gate, so it is clear context without full when-not guidance.

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