JobMojito

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

Annotations already declare the mutation profile (destructiveHint=true, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely useful behavior beyond them and beyond the schema: the id becomes an immutable URL segment that 'cannot be changed afterwards', and custom markdown 'replaces' the default grid rather than augmenting it.

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 contains two near-identical paragraphs: the second ('Creates a directory (page) in the coaching portal catalogue. A directory nests other directories through tags_sub...') is a verbatim paraphrase of the first. Only the trailing 'id is the catalogue URL segment and cannot be changed afterwards' sentence is unique, so a large share of the text is duplicated rather than earning 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?

An output schema exists, so return values need not be described, and the 14-parameter schema is exhaustively documented. The description covers the concept of a directory, its nesting/listing behavior, the markdown page replacement, and the immutability of the id — enough for an agent to call it correctly, with only the not-named update sibling and parent-existence prerequisites left 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?

Schema description coverage is 100% across all 14 parameters, including enum explanations for status/visibility/coach_plan and detailed semantics for tags_sub, tags_interview_set_filter and content_md. The description restates a few of these roles (tags_sub, tags_interview_set_filter, content_md) but adds no syntax, format or edge-case detail the schema does not already carry, so 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?

The description states a concrete verb+resource ('Create a directory (page) in the coaching portal catalogue') and clarifies what a directory actually is — a node that nests sub-directories and lists sessions. It never names or contrasts itself with the obvious sibling update_catalogue_directory, so discrimination relies on the tool name alone.

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 text explains that directories can be top-level or nested via parent_tag and can be customised via content_md, which hints at when those options apply. But there is no explicit 'use this to...' vs 'use update_catalogue_directory to...' routing, no stated prerequisites (a parent directory must already exist), and no 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 declare a non-idempotent, destructive, open-world write, so the safety profile is covered. The description adds real behavioral context beyond that: AI generation of description/questions/candidate expectations, provisioning of default steps, and optional embed-key provisioning. It stops short of disclosing credit implications or environment/webhook effects, which the schema carries instead.

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 lead sentence is well front-loaded with scope and the template-id modality insight. But the second paragraph largely restates the first — 'Creates a new interview / coaching / assessment definition' duplicates the opening 'Create a new interview' and re-lists the AI-generated artifacts, so a meaningful share of the text is redundant rather than additive.

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 48-parameter, 100%-documented schema with an output schema present, the description need not enumerate returns or fields, and it correctly covers the core operation, generation behavior, and a cross-reference to list_avatars. The one notable gap is sibling routing against create_interview_from_questions and update_interview, which a creation tool this broad should address.

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 the schema lacks: that interview_template_id determines the modality (voice-only vs realtime/pre-recorded avatar), a cross-field consequence not stated in the parameter's own description. It does not explain the 48-parameter surface broadly, but the key semantic link is captured.

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 ('Create a new interview') plus the non-obvious side effect that questions are auto-generated from position data, and notes it covers interview/coaching/assessment definitions. However, it never distinguishes itself from the close sibling create_interview_from_questions, leaving the agent to infer which creation path to take.

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 the verb: use this to originate a new interview from position data. There is no explicit when-not-to-use, no mention of create_interview_from_questions for question-driven interviews, and no prerequisites such as required permissions or the need to have a template/avatar already chosen beyond a passing 'see list_avatars' pointer.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: the AI rephrases supplied questions by default (a non-obvious behavioral trait), and it builds default and generated steps while optionally activating and optionally creating an embed key.

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 opening paragraph front-loads the key differentiator and the one actionable tip, and the second sentence is tight. The second paragraph partially restates the first ('creates a new interview definition set') but does add the step-building/activation/embed behavior.

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 100%-covered schema carries the parameter detail. For this complexity the description supplies the one thing structured fields cannot: the default rephrasing behavior and how to override it, plus the side effects (steps, activation, embed key).

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 46 parameters, including interview_tone='exact'. The description's mention of the exact-tone behavior largely echoes what the schema already states, so it 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?

States a specific verb and resource ('Create a new interview') and pins the distinguishing input ('from an explicit array of questions'). This implicitly separates it from the sibling create_interview, but the sibling is never named, so the agent must infer 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?

Provides one genuinely useful conditional — pass interview_tone='exact' when the wording is a script — but offers no guidance on when to choose this over create_interview, when not to use it, or what prerequisites (e.g. a valid interview_template_id) are needed.

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 mutation/open-world/destructive; the description goes far beyond them, disclosing billing destination (merchant vs coaching credits), recruiter visibility, attempt caps, the session flow (welcome → opening line → role-play → closing), that no AI question generation runs, and which omitted fields fall back to generic platform defaults.

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 and organized, but the portal guidance is stated twice in near-duplicate form — once in the bracketed intro paragraph and again under 'FIRST DECIDE portal' — and several defaults are repeated. The duplication is real waste, though the bulk of the length is load-bearing.

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 33-parameter creation tool with an output schema, the description supplies everything the agent needs: required-vs-optional intent, defaulting behavior, billing and visibility consequences, the session lifecycle, and how the template/avatar fields interact. Nothing material 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 already 100%, so the baseline is 3, but the description adds genuine cross-parameter meaning: it splits the four persona_avatar_* prompts by purpose (who_is / knowledge / progress / end_conditions) and warns that omitting persona_avatar_progress causes the avatar to have no arc, plus clarifies opening_line is a literal spoken line rather than a description.

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 verb+resource ('Create a role-play persona: an avatar that plays a defined role in a free-form conversation instead of a scored Q&A interview') and explicitly contrasts the result with its closest siblings create_interview / create_interview_from_questions. An agent can tell what this creates and how it differs from the scored-interview tools 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?

It opens with an explicit decision instruction ('FIRST CHOOSE portal') and gives when-to-use conditions for each branch: 'interview' for hiring/screening/assessment, 'coaching' for practice/training, plus the critical warning that the default is NOT the recruiter product. Alternatives and exclusions are stated outright.

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, but the description never explains why a report tool is destructive (e.g., overwriting a stored export) or what idempotency means here. It does add real context beyond annotations: PDF returns a signed URL, and the report is a human decision-support artifact, not an automated decision.

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-loads the scope and the human-reviewer caveat, and the second paragraph is compact. However, it restates 'Generate an interview result report' and the format list (HTML/PDF/JSON) that the first sentence already gave, so one sentence is partially redundant.

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 core selection logic is covered. But for a 7-parameter tool with a nested 10-property `export_features_result` object controlling transcripts, analytics, recordings and language, the description never mentions that customization surface or the 0.1-credit translation cost, leaving an agent to discover it only via the schema.

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

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

Schema description coverage is 43%, so the schema carries most parameter detail (store_file, template precedence, mojito_language_code credit cost). The description usefully clarifies the `interview_result_id` vs `interview_result_ids` choice, but adds nothing about `export_features_result`, the largest and most consequential parameter group.

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 ('Generate an interview result report') plus the output formats (HTML/PDF/JSON) and the single-vs-multi-result scope, which distinguishes it from list_interview_results and get_interview_result_details. The '[Results]' tag and decision-support caveat further sharpen what it produces.

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 says to provide either `interview_result_id` for one result or `interview_result_ids` for a combined report, and scopes the tool to a 'completed interview', but never names an alternative tool or states when to prefer get_interview_result_details or list_interview_results. Usage is implied rather than contrasted.

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 destructiveHint=true, openWorldHint=true, and non-idempotency, so the safety profile is covered structurally. The description adds useful context that the output is a public, token-signed link (i.e. the URL itself grants access without auth), but it does not explain why the operation is flagged destructive, whether tokens expire or are revocable, or whether repeat calls mint new tokens.

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

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

Two sentences, no filler, with the core action (signed public URL/token) front-loaded ahead of the conditional-id caveat. Every clause earns its place.

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

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

With an output schema present, return values need no explanation, and the cross-parameter conditionality is stated. The remaining gap is token lifecycle behavior, which matters for a security-sensitive share link but is not strictly required to make the call 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% and each id parameter already documents which `type` values require it, so the schema carries the load. The description's only addition is the general conditional rule, which is a useful summary but not new 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?

Specific verb (generate) plus resource (a signed public interview URL/token) scoped to an existing interview, profile, or result. It is easy to separate from siblings like create_interview or get_interview_definition, which produce different artifacts. It stops just short of 5 because it does not explicitly state how it differs from any named sibling.

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 implies the usage condition with 'The required id fields depend on `type`', routing the caller to the enum, but it never states when to use this tool versus alternatives or what preconditions must hold (e.g. the interview must already exist). Usage is inferable rather than explained.

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 read-only safety profile is covered. The description usefully adds the wholesale-replacement warning that motivates the read, but beyond that it does not disclose return format or pagination behaviour (the latter being a gap, though an output schema exists).

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 paragraphs restate essentially the same content — the second duplicates the first's enumeration of settings, content_md and sub-directories and the wholesale-replacement warning. The only sentence unique to the first paragraph ('how you verify that a session's tags place it in this directory') is buried inside the duplication, so structure and economy are poor.

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 tool with a complete output schema, full schema description coverage and strong annotations, the description supplies the needed purpose and read-before-update context. The only shortfall is that the guidance on sibling selection is not spelled out.

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

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

Schema description coverage is 100%, so all three parameters (id, merchant_id, conversation_id) are already documented in the schema. The description adds no parameter-level meaning of its own, 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?

States a specific verb and resource ('Read one catalogue directory in full') and enumerates the returned pieces (settings, content_md, sub-directories, matched sessions). It is clear enough to distinguish from most siblings, though it never explicitly names list_catalogue_directories as the alternative, so differentiation is left to inference.

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 use condition: read before updating because content_md, tags_sub and tags_interview_set_filter are replaced wholesale, so the current value is needed to extend rather than overwrite. That is actionable guidance, but it offers no when-not clause and does not contrast against the list sibling.

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 behavior, so the description's job is to add beyond that. It does: the two-domain allowlist (developer.jobmojito.com, help.jobmojito.com) and the automatic .md-variant fetch for developer docs are behavioral facts an agent could not infer from annotations or 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?

Three short sentences, front-loaded with the core action, then the source constraint, then the domain restriction. No filler and no repetition of schema or annotation content.

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

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

With an output schema present, return-value detail is correctly omitted. The provenance rule, domain allowlist, and format behavior cover what an agent needs to call this successfully; only an explicit 'what if the URL is rejected / not from search_documentation' failure note 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 baseline is 3 and the bar for extra credit is real. The description adds provenance semantics for url (must be a URL returned by search_documentation) and explains why raw vs. rendered content may differ (.md auto-fetch), neither of which is 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 (Fetch) and resource (a single documentation page) and immediately distinguishes itself from the sibling search_documentation by scoping to one page. An agent can tell exactly which of the 28 siblings this is.

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?

Names the prerequisite path explicitly: the URL must come from search_documentation, which tells the agent the correct call order. It also constrains where URLs may point, but does not state an explicit 'do not use this for X' exclusion or what to do when no URL is available.

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 genuine context beyond annotations: access is subject to row-level security, the returned `calc_definition_json` and `questions` array are disclosed, and it warns to preserve unchanged question `id`s.

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 restates the same round-trip point twice: the first sentence says questions come back in the format create_interview_from_questions accepts, and the second paragraph repeats that they are in the format accepted so they round-trip into update_interview. Redundancy costs it, though the round-trip concept 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?

An output schema exists, so return values need not be enumerated, yet the description helpfully sketches the response shape (calc_definition_json, ordered questions, basic metadata) and adds the row-level-security caveat. It is nearly complete for a read tool, with only minor redundancy and no explicit selection guidance between sibling reads.

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 both parameters (position_id and conversation_id) are already documented in the schema itself. The description echoes that position_id can be an interview-definition id or a position id but adds no syntactic or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Get) and resource (interview definition/configuration) and clarifies it includes the ordered `questions` array. It implicitly distinguishes itself from siblings like get_interview_result_details and list_interviews by naming the definition/configuration concept and the round-trip consumers create_interview_from_questions and update_interview.

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 frames the intended workflow: read the definition here, modify the array, send it to update_interview, and names the format-compatible siblings create_interview_from_questions and update_interview. It gives clear context but no explicit when-not-to-use or conditions for choosing between related read tools.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the bar is lower; the description adds meaningful context beyond them — that a result is a large record, that `view` is server-side narrowing and never affects the query, that `full` can exceed the result limit and fail, and the caveat that scores are assistive output for a human reviewer.

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-loads the purpose, then the `view` behavior, then the return summary. Slightly redundant — the default-omission point and the transcript/recording summary repeat what the schema and opening sentence already establish — but no sentence is wasted overall.

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 and annotations covering the safety profile, the description supplies what is still needed: the size caveat for `full`, the meaning of the default view, and the optional signed URLs. Only the absence of explicit sibling routing keeps it short of 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?

Schema description coverage is 100%, so the schema already documents every parameter, including the detailed `view` enum semantics and `get_signed_recordings`. The description largely restates that ('view controls how much of it comes back', 'Optionally attaches signed recording URLs') rather than adding new parameter meaning, 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 ('Get full interview result details including transcript and scores') and adds scope ('full ... including transcript'). It implicitly contrasts with the sibling list_interview_results by emphasizing 'full ... details' of one record, but never names that sibling, so the differentiation is left to inference.

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 real usage context: `summary` is for reviewing or comparing candidates, `full` should only be requested when the raw fields are needed, and the default is described. It never explicitly says when to use this tool instead of list_interview_results or get_interview_definition, but the within-tool guidance is 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description adds real behavioral value beyond that: a 1000-record page cap and, importantly, the zero-suppression rule that absent day/event pairs must be treated as count 0. It doesn't cover auth requirements or rate limits, keeping it short of 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 the core purpose, followed by scope, drill-down, cap, and the sparse-result caveat in a logical order. It is a little dense, and the '[Results]' prefix is unexplained, but every sentence carries weight.

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 still covers scope, pagination cap, drill-down, and the zero-suppression caveat. The conversation_id lifecycle is fully specified in the schema parameter, so the definition is essentially complete for correct invocation.

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 parameters and the baseline is 3. The description reinforces scoping (merchant_id override) and drill-down behavior, but its phrase 'drilled to a single interview' omits the position_def_set case that the schema documents, adding marginal rather than corrective value.

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: retrieve a merchant's daily event-count time-series over a date range, explicitly tied to the admin-portal analytics events graph. This is clearly distinguishable from siblings like get_merchant_credit_usage and get_merchant_status, which concern billing and account state, not event analytics.

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 usage context: scoped to the token's merchant by default, with merchant_id override restricted to admins/sub-merchant operators, and optional drill-down to an interview/position. It stops short of naming alternative tools or stating when-not to use it, so no explicit alternatives are provided.

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, so safety is covered; the description adds genuinely useful behavior beyond that — result ordering (most recent first), the 1000-record page cap, the admin-only override semantics, and where the consumed credit figure lives (stats.credit_amount). It stops short of describing auth failure modes or rate limits.

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

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

A short bracketed marker, a one-line statement of purpose, then two dense sentences covering scope, ordering, field location and the page cap. Front-loaded and nearly waste-free, though the parenthetical event list ('interview, pre-screening, public avatar, simulation, …') is slightly loose.

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 and full parameter coverage, the description only needs to add the things structured fields don't carry — ordering, the 1000-record cap, scoping rules, and where the credit amount is found — and it does all of that. Nothing an agent needs to invoke this read tool correctly 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%, so the schema already documents limit, offset, merchant_id, interview_id and conversation_id, including the interview-vs-position detection logic. The description largely restates the merchant scoping rule rather than adding new parameter meaning, 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 ('Get the merchant's credit usage') and immediately sharpens it into a per-event credit-usage ledger listing every billable analytics event that consumed credits, ordered most recent first. That level of detail lets an agent distinguish it from sibling reporting tools like get_merchant_analytics or get_merchant_status without opening any schema.

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

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

It gives scoping context ('scoped to your token's merchant, or a merchant_id override for admins / sub-merchant operators') and a pagination cap, which implies when the tool applies, but it never names an alternative or states when NOT to use it versus the other merchant/interview reporting tools. Usage is implied rather than instructed.

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, and openWorld, so the safety profile is covered. The description adds genuine behavioral context beyond that: it is scoped to the token's merchant unless an admin override is used, and it echoes back the caller's profile_id, default_merchant_id, and effective merchant_id. It does not, however, discuss rate limits or freshness of the 14-day history.

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 redundant: the opening sentence and the following paragraph both enumerate the same snapshot contents (credit balances, subscription, pending-work counts, candidate/result totals, invitation headroom). The second paragraph restates the first with minor added detail rather than front-loading new information, wasting space.

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 annotations cover the safety profile, so the description needn't explain return values. It adequately conveys scope, admin override behavior, and echoed identifiers, leaving only minor gaps around when to prefer it over sibling reporting tools.

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 both parameters (including the detailed conversation_id continuity instructions) are fully documented in the schema. The description's mention of merchant_id scoping largely restates the schema and adds no syntax or format detail, 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 ('Get a merchant status snapshot') and enumerates what the snapshot contains (credit balances, subscription, pending-work counts, candidate/result totals, invitation headroom). It is clearly distinguishable from a generic read, though it never explicitly contrasts itself with the closest siblings get_merchant_analytics or get_merchant_credit_usage.

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 scoping rules ('Scoped to your token's merchant (or a merchant_id override for admins / sub-merchant operators)') and flags itself as [Admin], which is useful context. However, it offers no explicit when-to-use or when-not-to-use guidance versus the many sibling merchant/reporting tools, 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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds substantial behavior beyond that: it renders a UI, it requires the agent to STOP and await user selection before proceeding, and it defines a persistent merchant_id propagation rule for all subsequent JobMojito calls. That is exactly the kind of interaction-model context 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?

The critical directive (render the picker, don't list text) is front-loaded, and every sentence is actionable rather than filler. It is slightly repetitive in restating the trigger as both an ALWAYS and a DO-NOT clause, but the redundancy is purposeful emphasis rather than padding.

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 UI-rendering tool with no output schema, the description covers everything needed: when to invoke, what is displayed, that control returns to the user, and how to use the resulting merchant_id afterward. Nothing an agent needs to call this correctly 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?

There is a single parameter, conversation_id, and the schema already documents it at 100% coverage including the lifecycle rules (pass unchanged, don't invent, don't reset). The description adds no additional meaning about this parameter, so the baseline of 3 applies. The merchant_id mentioned is not a parameter of this tool but downstream guidance.

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 renders an interactive JobMojito merchant picker UI — and implicitly distinguishes itself from text-listing siblings such as list_my_merchants by forbidding that approach. An agent can tell what this tool does and how it differs from list-oriented siblings without opening any schema.

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

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

It gives explicit trigger conditions ('ALWAYS call this when the user wants to choose, switch, or set a merchant, or when a tool needs a merchant_id and none is selected') and explicit exclusions ('Do NOT list merchants as text or ask the user to type a name — render this picker instead'). The post-call routing ('pass merchant_id=<chosen id> on every JobMojito call, omit it for the user's own account') closes the loop on what to do next.

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 description is free to add the traits that matter here: large rows returned 15 at a time, paging via `offset` while `pagination.has_more`, a 1000-record page cap, and legacy integrations that render but are unusable for new interviews. These are concrete operational caveats beyond the annotation surface.

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?

Purpose and the type taxonomy are front-loaded, and the second paragraph handles scoping and page caps. Pagination is mentioned twice (first and second paragraph), which is a small redundancy, but nearly every sentence carries distinct 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?

With an output schema present, return-value detail is not needed, and the description still covers scoping (token merchant vs. `merchant_id` override), paging, status/archive filtering, and legacy-type caveats. An agent has everything required 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to the `type` enum (each value's modality, credit cost, and whether it can early-stop) and to paging behavior (`offset` with `pagination.has_more`, `type`/`filter_text` narrowing). That exceeds what the bare enum listing conveys.

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 first sentence gives a specific verb and resource ('List available avatar/voice templates') and immediately explains what each returned `type` means in terms of interview modality, credits, and interactivity. It also distinguishes this from the create-interview tools by stating that an item's `id` is the `interview_template_id` those tools consume.

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 clearly routes usage: 'pick the template whose type matches the experience you want' and warns that `offline_elai`/`offline_synthesia` are legacy and cannot create new interviews. It also explains how to page and narrow. It stops just short of explicitly stating when to call this vs. get_interview_definition or list_languages, so it is clear context without explicit alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds that results are paginated and capped at 1000 records per page, which is modest extra context, but says nothing about total counts, auth failures, or ordering interactions.

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 short sentences, front-loaded with the core operation and followed by scope then pagination constraints. The '[Candidates]' tag is minor noise but nothing is padded or redundant.

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 and 100% parameter coverage, the description need not explain return values. It correctly covers scope and pagination cap; the only gap is that it does not position the tool against the many list_* siblings.

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

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

Schema description coverage is 100%, so all nine parameters (including enums, defaults and the conversation_id contract) are already documented in the schema. The description only reinforces the merchant_id override, adding no syntax 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?

States a specific verb+resource ('List the merchant's candidates') and disambiguates the term by defining it as the admin-portal candidates list. It is clearly distinguishable from list_interviews / list_interview_results by resource, though it never names a sibling 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?

Usage is only implied: the description explains the merchant scoping (token's merchant, or a merchant_id override) which tells the caller when the tool applies, but it never states when to prefer this over list_interviews or list_interview_results, nor any 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 readOnly/idempotent/non-destructive, so safety is covered. The description still adds real behavioral value with pagination semantics (25 per page, page with offset while pagination.has_more is true) and the include_public=false scoping behavior, though it doesn't fully explain cursor/result-shape behavior beyond that.

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 contains two near-identical paragraphs that restate the same points twice — list your own plus public directories, use it to find an id/parent_tag, the Markdown page is excluded. This duplication wastes space, and the second paragraph even cites a non-sibling name (catalogue-tag-get), reducing clarity.

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 and rich annotations, the description needn't explain return values, and it covers the main use cases and the key scoping caveat. It is slightly incomplete on filtering interaction nuances but nothing essential to correct invocation 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%, so the schema already documents all ten parameters in detail (conversation_id, filter_text, visibility, etc.). The description adds only marginal meaning on a few params (parent_tag nesting, include_public=false), which lands at the baseline for a fully documented 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 (list) and resource (coaching-catalogue directories) plus the exact scope: the merchant's own directories plus platform-wide public ones. It explicitly distinguishes itself from get_catalogue_directory, which serves the Markdown page this tool excludes.

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 concrete when-to-use triggers: find a directory id before updating, pick a parent_tag for a new directory, or walk the tree with parent_tag. It also names the alternative (get_catalogue_directory) and the condition that selects it (reading the Markdown page).

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), so the description earns credit for adding non-obvious behavior: default 20 rows per call, a 1000-record per-page cap, and that results are scoped to the token's merchant unless merchant_id is overridden. It also notes rows carry candidate scores and recruiter risk flags, which helps an agent anticipate payload shape.

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

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

Roughly 85 words is well-sized for a 13-parameter paginated tool, and the paging instruction is front-loaded immediately after the purpose. There is mild redundancy between the opening 'List the merchant's interview results' and the second paragraph's 'Paginated list of a merchant's interview results', 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?

An output schema exists, so return values need no explanation, and the description covers the things structured fields can't: the paging loop, the per-page cap, and merchant scoping. What's left unstated is minor (e.g. it doesn't flag that `conversation_id` must be echoed back), and that detail is already carried in the schema.

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

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

Schema coverage is 100%, so the schema already documents all 13 parameters (including enums, defaults, and the merchant_id admin restriction), setting the baseline at 3. The description adds only light semantic value by tying paging params together via `offset`/`has_more` and restating the 20-default/1000-cap behavior already present 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?

The description states a specific verb and resource ('List the merchant's interview results', 'Paginated list of a merchant's interview results') and identifies it as the admin-portal results list, which distinguishes it somewhat from list_interviews/get_interview_result_details. It never names the detail-fetching sibling as the alternative, so the differentiation is implied rather than explicit.

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 concrete operational guidance: page with `offset` while `pagination.has_more` is true, or narrow with `tab`/`interview_id`/`filter_text`. That tells an agent how and when to drive the tool, but no exclusions or named alternatives (e.g. get_interview_result_details for a single record) are provided.

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 and openWorld, so the safety profile is covered. The description adds genuinely useful operational context on top: the 1000-record per-page cap, the merchant-token scoping default, and the admin-only restriction on merchant_id. It stops short of describing what a page contains or how to page through beyond limit/offset.

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 paragraphs, front-loaded with the resource label, then scope and cap. 'Paginated list' mildly restates the title, but the second sentence carries real information without padding.

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, all ten parameters are documented in-schema, and annotations carry the safety profile. The description supplies the remaining missing pieces an agent needs: scope resolution and the page-size ceiling.

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 ten parameters including enums, defaults, ranges and examples; baseline 3 applies. The description only reinforces scoping (merchant_id override, 1000 cap) and adds no syntax 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?

States a specific verb and resource ('List the merchant's interview definitions') and clarifies it is the admin-portal interview definition list, which implicitly separates it from list_interview_results. It never explicitly names a sibling, so differentiation is left to the reader's inference between 'definitions' and 'results'.

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 scoping guidance — the list is bound to the token's merchant unless an admin/sub-merchant operator passes merchant_id — and states the 1000-record page cap. However, it never says when to use this tool instead of get_interview_definition or list_interview_results, and there are no exclusions or prerequisites beyond the scope note.

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 the safety profile is covered. The description adds the '[Admin]' qualifier and the returned field list, but discloses nothing about permissions, rate limits, or freshness beyond that.

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 and the follow-up sentence overlap heavily, repeating English/local names and the SVG flag URL, and the second sentence drops the 'per-interface enablement flags' and 'Azure speech accents' items without explanation. Front-loading is fine but the redundancy 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?

For a read-only discovery tool with full annotations and an output schema, the definition is essentially complete. The only gap is the missing routing guidance, and the restated return-value prose is redundant against the output schema but not harmful.

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

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

The single parameter (conversation_id) has 100% schema description coverage with detailed protocol instructions, so the schema carries the load. The description mentions 'code' only as a returned field, adding no input-parameter meaning; 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 verb and resource ('List supported platform (mojito) languages') and enumerates the returned fields, so an agent knows exactly what it yields. It is clear but does not need sibling differentiation, since no other tool in the list serves this purpose.

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 sentence 'Use the `code` as `mojito_language_code` when creating interviews or personas' tells the agent how to consume the output, not when to call this tool versus alternatives. There is no explicit when-to-use or when-not-to-use 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 safety (readOnly, idempotent, non-destructive, closed-world), yet the description adds genuinely new behavioral context: the fallback trigger condition, the downstream protocol (pick a merchant then pass merchant_id=<chosen id> on later calls, omitting it for the own account), and the anti-pattern to avoid. That multi-step flow context is not derivable 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?

Front-loads the decisive constraint ('FALLBACK merchant list for clients WITHOUT UI support') before any procedural detail, and every subsequent sentence carries an instruction. It is slightly dense with parentheticals and backticked names, 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 an output schema present, return values need not be explained, and the remaining burden — fallback condition, alternative tool, follow-up call protocol — is fully covered. Nothing an agent needs in order to invoke this correctly 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%, so both parameters are already documented, which sets a baseline of 3. The description goes beyond that by explaining how the returned selection should be threaded into subsequent calls via merchant_id, including the omit-for-own-account case — semantics the schema for this tool cannot express.

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 ('merchant list') and immediately qualifies its scope as a FALLBACK path for clients without UI support, which separates it from jobmojito_configuration and list_sub_merchants. An agent knows both what it returns (own account plus sub-merchants) and what it is not for.

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 names the preferred alternative (jobmojito_configuration), the condition that selects this tool (client cannot render MCP App UI), and two prohibitions: do not use it to choose/switch merchants when a UI exists, and do not hand-format a merchant list as text. This is textbook when/when-not/alternative 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 declare a safe read (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the safety profile is covered. The description still adds useful non-annotation context: visibility is row-level-security enforced and results are capped at 1000 per page, which tells the agent to paginate rather than expect a full dump.

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 short sentences with the admin scope front-loaded and no filler. The parenthetical restating 'the admin-portal sub-merchants list' is mildly redundant with the opening sentence but does not bloat the definition.

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 prose, and 100% schema coverage handles parameters. The description supplies the remaining behavioral essentials (admin-only, RLS visibility, page cap) for a read-only paginated list, leaving nothing an agent needs 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 every parameter including limit, offset, order_by, filter_text, merchant_id, and conversation_id is already documented in the schema. The description adds no parameter-level meaning beyond that, which is the correct baseline of 3 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 specific verb and resource ('List sub-merchants') and scopes it with the '[Admin]' prefix plus 'the sub-merchants the caller administers'. It is clear what the tool returns, but it never names the obvious sibling list_my_merchants, so the 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?

The '[Admin]' marker and 'admin-portal sub-merchants list' phrasing imply when this tool applies, and the merchant_id schema note explains scoping. However, there is no explicit statement of when to prefer this over list_my_merchants or any other list tool, and no prerequisites are called out.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the bar is lower. The description adds useful context beyond that: it is an upsert ('Registers (or updates)'), returns one-time URLs, and discloses the two auth modes, but it does not say who is notified, whether existing profiles are overwritten, or the consequences of the destructive behavior.

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

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

Two tight sentences, front-loaded with the action and outcome. Mild redundancy in the second sentence (the one-time URL was already implied by 'return their personal interview links'), 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?

With a rich schema, an output schema, and safety annotations, the description needs only to frame the operation and auth modes — both of which it does. It is complete enough for an agent to call correctly, though it stops short of routing the agent away from overlapping siblings.

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 each parameter thoroughly (phone semantics, merchant_id auth conditions, conversation_id protocol). The description only restates the merchant_id/service-key rule, adding essentially nothing beyond the structured fields — the baseline 3.

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 ('Register users/candidates for a specific interview') plus the return value (personal interview links), so the core action is unambiguous. It does not, however, distinguish itself from the sibling 'generate_interview_url', which plausibly overlaps in the 'get a link' space.

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 authentication context (Supabase user JWT vs service key, with merchant_id required for the latter), which hints at when the tool is callable, but offers no explicit when-to-use/when-not guidance relative to siblings like generate_interview_url or request_another_interview_attempt. Usage is implied rather than 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful detail beyond that: it marks the result unsuccessful, resets it to draft, and clears the recruiter decision — a concrete account of what state is destroyed and changed.

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, with the action front-loaded and the state-change consequences following. The '[Results]' tag adds categorization value; nothing is padding.

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 not be explained, and annotations cover the destructive profile. The description covers the mutation's effects well; only permission/auth prerequisites are unstated, a minor gap for a simple two-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?

Schema coverage is 100%; interview_result_id is documented in the schema and conversation_id carries an extensive description there. The description adds no parameter 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?

States a specific verb+resource ('Re-open a submitted interview result') and frames the outcome ('so the candidate can retry'). The 'interview result' scoping cleanly separates it from sibling interview-level tools like create_interview, set_interview_state, and get_interview_result_details.

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 clause 'so the candidate can retry' implies the use case, and 'submitted (active + completed)' narrows the applicable state. But no alternative is named (e.g., vs set_interview_state) and no explicit when-not condition is given, 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context beyond them: the search fans out over both sources in parallel and returns a merged, source-labeled result rather than requiring separate calls. It does not discuss pagination or result ranking, keeping it just short of 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 the core claim ('Search ALL JobMojito documentation. This is the single entry point.') before any detail, and the bullet list is dense and informative rather than padding. It runs slightly long for a search tool, costing it the top score.

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-format details are not needed. The description still covers purpose, source semantics, when to invoke versus the read-full-page sibling, and the parallel-search behavior — nothing an agent needs to call it correctly 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 baseline is 3. The description goes further by explaining what the 'developer' and 'help' source values actually cover (API reference/schemas/webhooks vs. recruiter/candidate/admin product guides), which gives semantic meaning the bare enum-less source parameter lacks.

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 (search) and resource (ALL JobMojito documentation) and explicitly positions itself as 'the single entry point' that searches both sources in parallel. It names get_documentation as the separate follow-up tool, so an agent can distinguish it from siblings without opening any schema.

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

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

Gives explicit when-to-use ('whenever you need to understand how a feature, endpoint, field, or workflow works — including before calling an action tool you're unsure about') and names the alternative path (call get_documentation(url) to read the full page). It also removes a decision point by stating the agent need not choose a source.

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 destructiveHint, idempotentHint, openWorldHint and non-readonly, so the safety profile is covered. The description adds independent value by disclosing the embed-key side effect (creating vs removing embed keys) and the cross-parameter requirement. Minor confusion: the intro examples 'open, closed' do not appear in the actual enum.

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 scope and followed by the values and the at-least-one requirement. No filler, though the duplicated 'e.g. open, closed' example is slightly redundant and inconsistent with the enum.

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 annotations cover the mutation semantics. The description supplies the lifecycle values, the embed-key side effect and the input constraint, leaving only sibling differentiation 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?

Schema description coverage is 100%, so the baseline is 3 and the schema already documents each field. The description adds the cross-parameter constraint that at least one of `status`/`is_embedded` must be supplied and frames the two as an either/or, which is meaning not present in the schema.

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

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

States a specific verb and resource (change the lifecycle status of an interview/position) and enumerates the status values plus the embed-key side operation. It is clear what the tool does, but it never distinguishes itself from the sibling update_interview, leaving the agent to guess which one to pick for a status change.

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 one real usage constraint: 'Provide at least one of `status` or `is_embedded`.' That is useful, but there is no guidance on when to prefer this tool over update_interview or generate_interview_url, and no mention of prerequisites or when-not-to-use conditions.

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 destructiveHint=true and idempotentHint=true, so safety is covered. The description adds real behavioral value beyond that: partial-update semantics ('only the fields present in the request body are written') and the null-clears-a-field rule ('sending null removes the custom page'). It does not expand on the destructive profile (e.g. that replacing tags_sub drops the whole previous list is only in the schema), which keeps it at a solid 4.

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 tool name and operations, but the two paragraphs are largely redundant: 'Only the fields you send are changed' and 'Only the fields present in the request body are written' say the same thing, and the four supported operations are listed twice. The duplication costs it a point.

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 annotations carry the safety profile. The description covers the partial-update contract and the main editable fields, leaving only minor gaps (destructive scope of list replacements is schema-only), so it is nearly complete for a 12-param mutation.

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 12 parameters thoroughly, including enums and examples. The description restates a few field meanings (tags_interview_set_filter, tags_sub, content_md) but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (update) and resource (coaching catalogue directory) and enumerates the concrete operations: rename, re-point session listings, re-order sub-directories, author the Markdown page. Purpose is unambiguous, though it never names its create/get siblings, so differentiation is left to the tool name rather than the prose.

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 implies when to reach for it by listing the field-level operations it supports, but offers no explicit when-to-use/when-not guidance and never names an alternative (e.g. create_catalogue_directory for a new id). Usage is inferable rather than 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?

Annotations declare destructiveHint=true and idempotentHint=true, so the safety profile is known, and the description goes well beyond them: partial-update semantics (only sent fields written, null clears nullable), the diff mechanics (match on external_id then id then content; edited questions unlink-and-recreate; nothing is ever deleted because questions are shared records), the active-interview restriction on question edits, and the immutable `mojito_language_code`.

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 and scannable, but the description is essentially written twice: the second paragraph restates the first's points about questions handling, the welcome/thank-you steps, and the multi-stage 422. A large fraction of the text is redundant with itself, which dilutes rather than adds 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?

For a 44-parameter mutation tool with an output schema available, the description covers what the structured fields cannot: partial-write semantics, question-diff behavior and its response field (`questions_diff`), status-dependent editability, and immutable fields. Nothing an agent needs to call it correctly 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 baseline is 3, but the description adds real operational meaning on top of the schema — the read-edit-resend workflow for `questions`, the fact that re-sending an unchanged array is a no-op, and the `tags`-as-catalogue-mapping key. These are workflow semantics rather than mere parameter restatement.

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 ('Update the configuration of an existing interview/position') and immediately scopes it: single-stage interview vs multi-stage position, with the exact field families affected (name, description, avatar template, recording, scoring, tags). An agent can distinguish it from create_interview and set_interview_state 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 when/when-not guidance: omit `questions` to leave questions alone, read the interview first and send the whole array back, use `tags` for coaching-catalogue placement, and for multi-stage positions update the individual stage rather than sending interview-only fields. It even names the failing field (`candidate_expectations_json`) and the 422 outcome.

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 the mutation/destructive/non-idempotent profile, so the bar is lower. The description still adds real behavioral value beyond them: it discloses that processing is asynchronous ('queues it for processing') and that the file may arrive as multipart binary or JSON base64. It does not address permissions or duplicate-upload consequences.

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 compact sentences, front-loaded with the bracketed domain tag and the core action, then the processing/format details. No filler and nothing redundant with 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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies the async-processing and encoding context an agent needs; only permission/auth requirements and behavior on re-upload of the same document are left unstated.

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, but the description genuinely extends the 'file' parameter by explaining the two accepted encodings (multipart binary vs. application/json base64), which the schema's 'format: binary' alone does not convey.

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 ('Upload and process a knowledge base document') and reinforces it with 'Uploads a document to a knowledge base store and queues it for processing.' No sibling tool performs document upload, so the scope is unambiguous even without explicit differentiation.

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 description (adding a document to a KB store) and the dual content-type note hints at two invocation paths, but there is no explicit when-to-use/when-not guidance or named alternative. Since no sibling competes for this job, the omission is tolerable but still a gap.

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