JobMojito

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuine behavioral fact beyond the schema: the chosen id becomes the URL segment and 'cannot be changed afterwards'. It does not explain the destructiveHint=true annotation or the permission gates (public visibility, merchant_id being admin-only), 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 description is two paragraphs that substantially restate each other — nesting via tags_sub, session listing via tags_interview_set_filter, and custom content_md appear twice. Only the id-immutability sentence in the second paragraph is new, so roughly half the text is redundant padding rather than earned 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 15 parameters, an output schema, and full annotations, the structured fields carry most of the burden. The description adequately conveys purpose, the language/translations model, and id immutability, but omits the permission constraints and the merchant/language defaults that an agent needs to call it correctly without reading 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 100%, so every one of the 15 parameters is already documented in the schema. The description names a handful of fields (tags_sub, tags_interview_set_filter, content_md, translations, id) but adds no syntax or format meaning beyond what the schema states, so the baseline 3 applies.

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

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

The description states a specific verb+resource ('Create a directory (page) in the coaching portal catalogue') and explains what a directory is structurally (nests sub-directories, lists sessions via tag filter, carries custom Markdown). It never names or contrasts the obvious siblings create/update/get/list_catalogue_directory, so an agent gets a clear purpose but no differentiation signal.

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

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

There is no when-to-use guidance, no mention of update_catalogue_directory as the alternative for existing directories, and no stated prerequisites. The trailing 'Coaching-platform feature' is a vague context tag, not usage direction, leaving the agent to infer when this tool is appropriate.

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 idempotentHint=false, so the agent knows this is an irreversible outward-facing write. The description adds useful behavioral detail beyond that: AI generation of description/questions/expectations, provisioning of default steps, and optional embed-key provisioning. It still omits consequences of destruction and permission requirements, so it is solid but not rich.

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

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

Three tight sentences, front-loaded with the core action and the most consequential parameter behavior. Minor redundancy between the two paragraphs ('Create a new interview' vs 'Creates a new interview/coaching/assessment definition') 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 48 parameters at 100% schema coverage, full annotations, and an output schema, the description need not document fields or return values. It supplies exactly the non-structured context an agent needs: the generative behavior and the embed-key side effect. Nothing material for 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 coverage is 100%, so the baseline is 3. The description contributes extra meaning by explaining that interview_template_id governs modality (voice-only vs avatar) and routing the agent to list_avatars. That is a real value-add beyond the schema's field descriptions, warranting a step above 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+resource ('Create a new interview') and specifies the generative behavior ('auto-generate its question sequence from position data'), which implicitly separates it from create_interview_from_questions. It also clarifies a key driver (interview_template_id sets modality). It does not, however, explicitly name its closest sibling or contrast them, so it stops short of a 5.

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

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

It offers a pointer ('see list_avatars') for choosing a template/modality, which is genuine selection guidance. But it never states when to prefer this tool over create_interview_from_questions or create_persona, nor any prerequisites or exclusions. Usage direction is implied rather than spelled 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 cover the write/destructive/open-world profile, and the description adds real behavior beyond them: the AI rephrases caller wording by default, the tool builds default and generated steps (not just the literal array), and it optionally activates the interview and optionally creates an embed key. It omits credit cost and non-idempotency, but the disclosure is solid given the annotations carry the safety burden.

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 is front-loaded and the tone caveat is well placed, but the second sentence largely restates the first ('create ... from an explicit array of questions' vs 'Creates ... from a caller-provided array of questions'), spending a full paragraph on information already conveyed.

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 46 parameters, an output schema present, and safety annotations supplied, the description covers the essential mental model: it is a create-from-array operation with AI rephrasing by default, deferred step generation, and optional activation/embed. Return values are handled by the output schema and parameter details by the fully covered schema, so remaining gaps are minor.

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 baseline is 3, and the description earns an increment by surfacing the single most consequential parameter decision — the default rephrasing vs. interview_tone="exact" for scripted wording — which is the primary way an agent can get this call wrong across 46 parameters.

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 ('Create a new interview from an explicit array of questions') and the qualifier 'explicit array of questions' implicitly distinguishes it from the sibling create_interview, which generates questions from a job description. However, it never names that sibling, so the agent must infer the contrast from the phrase 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?

It gives a genuinely useful conditional for one decision — use interview_tone="exact" when the wording is a script (compliance, translated, legally reviewed). But there is no tool-level when-to-use guidance: nothing says when to pick this over create_interview, nor what the prerequisites (template id, language) are. 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 declare destructiveHint=true, openWorldHint=true and non-idempotent, and the description goes well beyond them: it discloses billing (merchant credits vs the mentee's coaching credits), visibility to recruiters, the attempt cap interaction with interview_attempts, the session flow (welcome → opening line → role-play → close), and the effect of omitting optional fields (generic 'Hello' defaults). These are rich, actionable behavioral traits.

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 content is front-loaded and the first sentence frames the tool well, but the portal decision is restated three separate times ('FIRST CHOOSE portal', 'FIRST DECIDE portal', plus the inline paragraph), producing substantial redundancy. Length is partly justified by 33 parameters, but the repetition costs it here.

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

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

Given a 33-parameter mutation tool with an output schema (so return values need not be described), the definition covers the decisive field (portal), the session mechanics, the persona prompt roles, and the consequences of omitted fields. Nothing essential 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 description coverage is 100%, so the baseline is 3, but the description adds genuine cross-field meaning: it explains that portal selects the whole product and drives billing/visibility/attempt behavior, that opening_line is a literal spoken line rather than a description, and how the four persona_avatar_* prompts divide responsibilities. This is more than restating the schema.

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

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

It states a specific verb and 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 differentiates the two products it can build, which separates it from the create_interview / create_interview_from_questions siblings.

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

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

It gives explicit when-to-use routing: use portal="interview" for ANY hiring, screening or assessment use, coaching (the default) for practice/training, and warns repeatedly that the default is NOT the recruiter product. The alternative siblings and the selecting condition are both named.

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=false, destructiveHint=true and idempotentHint=false. The description adds genuinely new behavior: the report is created private ('Only me'), it can be shared later from the admin, and the response carries id, version and admin_url — plus a directive to tell the user about sharing.

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 body is duplicated almost verbatim — the 'Only me' privacy note and the preview_report instruction each appear twice, and the second paragraph restates the first wholesale. Front-loading is fine, but half the text fails to earn its place.

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

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

For a create tool with an output schema, the description covers the essentials an agent needs: the payload schema, the validation prerequisite, the default privacy state, and the share path. The destructive annotation is never explained, which is a minor remaining 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 schema already documents definition, merchant_id and conversation_id in depth, including nested block semantics. The description adds no parameter meaning beyond restating the definition's schema id, 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 ('Save a new custom report from a definition') and pins the payload contract ('schema jobmojito.report/v1'). An agent can distinguish this from preview_report, update_report and run_report 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?

Explicitly routes the agent to preview_report first ('Check the definition with preview_report first'), which is a real prerequisite. It does not, however, say when to prefer update_report over creating a new report, so one gap remains.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine context beyond them: that updates replace content_md/tags_sub/tags_interview_set_filter wholesale (motivating the read), and that other language versions live in `translations` with `languages` defaulting first.

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 restating the same purpose, return fields, and read-before-update rationale. This is pure duplication rather than earned length, though the first sentence is well 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?

With an output schema present, return values need not be explained, and annotations carry the safety profile. The description covers purpose, the read-before-write workflow, and language/translation handling, leaving little an agent needs 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 id, merchant_id, conversation_id and mojito_language_code in detail; baseline is 3. The description adds only marginal nuance (that `languages` lists translations with the default first) beyond the mechanical schema text.

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

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

States a specific verb and resource ('Read one catalogue directory in full') and enumerates exactly what is returned: settings, content_md, resolved sub-directories, and matched sessions. This clearly distinguishes it from the sibling list_catalogue_directories (singular, full read vs. listing).

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 guidance ('Read before updating') tied to the wholesale-replacement semantics of content_md, tags_sub and tags_interview_set_filter, and explains the verification use case for tags. It stops short of naming a specific alternative sibling or stating when not to use it, so it does not reach 5.

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

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

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?

With annotations already covering readOnly/idempotent/non-destructive, the description adds real value: scores are assistive (not authoritative) output, the record is large, the default view omits raw machine assessment data, and signed recording URLs are optional. It does not mention pagination or auth requirements, but the behavioral additions clearly exceed 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?

The lead sentence front-loads the purpose and the size/view tradeoff. The second paragraph slightly restates the first (transcript + AI assessment, signed recordings), which is minor redundancy, but overall the description is tight and appropriately sized.

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-value detail is unnecessary, and the description covers the non-obvious parts: view granularity, the assistive nature of scores, and large record size. Only the sibling-routing question (why this over list_interview_results) is left unaddressed.

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

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

Schema description coverage is 100% and the view enum is documented in exhaustive detail in the schema itself. The description only restates the default and what it omits, adding little beyond structured data — the expected baseline for full schema coverage.

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

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

States a specific verb+resource ("Get full interview result details including transcript and scores") and clarifies the payload scope. It does not explicitly name the nearest sibling (list_interview_results), so an agent must infer the distinction from context rather than being told it.

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 implied guidance via the view-default note and the caution that scores are assistive output for a human reviewer. However, the concrete when-to-use routing (summary for comparing candidates, full only when assessment details are needed) lives in the schema, not the description, and no alternative tool is named.

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 cover the read-only/idempotent safety profile, and the description adds real behavioral context beyond that: whole-replacement semantics of the definition, the version-match requirement for update, and the conditional fact that editors also receive an unpublished draft. It does not cover rate limits or error/failure behavior, so it stops 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?

The workflow warning is front-loaded, which is good, but the second paragraph largely restates the first ('JSON definition, visibility, your access, its version'), repeating content rather than earning space. The duplication is small but costs 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 description supplies the workflow hook (read-before-update), permission-scoped payload, and version semantics. An agent has everything needed to invoke it correctly, though nothing is said about failure modes.

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 id, merchant_id, and conversation_id are already fully documented in the schema, including who may use merchant_id and the conversation_id protocol. The description adds no parameter-level meaning beyond that, 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 ('Get a custom report's JSON definition, visibility, your access and its version') and enumerates exactly what comes back. It is clearly distinguishable from siblings like list_reports, run_report, preview_report, and update_report.

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 routes the agent: 'Read it before update_report' with the reason (definition is replaced whole, version must match). This names the alternative tool and the condition that selects it, leaving nothing to inference.

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

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

Annotations 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 read-only, idempotent, non-destructive, open-world, so the safety bar is pre-cleared. The description adds real behavioral context beyond them: page size of 25, offset paging while `pagination.has_more` is true, that deleted directories are never returned, and that the custom Markdown page is excluded from results.

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

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

The description contains two paragraphs that repeat the same content almost verbatim: 'Start here to find a directory id', 'pick a parent', 'walk the tree with parent_tag', 'The custom Markdown page is not included', and the pagination note all appear twice. Roughly half the text does not earn its place, and the second paragraph buries the new detail (include_public=false, status='public') behind duplication.

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

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

An output schema exists, so return values need not be explained, and the description still adds useful paging and result-set facts. For a 10-parameter read tool with full schema coverage, an agent has everything needed to call it correctly; only the duplicated alternative tool name leaves a small gap.

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

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

Schema description coverage is 100%, with enums on status/visibility/include_public/mojito_language_code, so the schema already documents all ten parameters. The description restates include_public, parent_tag and offset behavior but adds no syntax or format detail beyond the schema, matching the baseline-3 case.

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 coaching-catalogue directories you can see') and immediately delimits scope ('your merchant's own plus the platform-wide public ones'). It is clearly distinguishable from siblings like get_catalogue_directory, create_catalogue_directory and update_catalogue_directory.

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: 'Start here to find a directory id, to pick a parent for a new one, or to walk the tree with `parent_tag`' and 'find a directory id before updating one'. It also routes around the omission ('The custom Markdown page is not included — read it with get_catalogue_directory'). Minor flaw: the same alternative is later called 'catalogue-tag-get', a name that does not match any sibling, creating ambiguity about which tool to call.

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

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

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 cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for going beyond them: it discloses the 403 failure mode when custom reports are disabled and prescribes the correct recovery (tell the user to contact JobMojito, do not retry). It does not discuss rate limits, caching, or response size, so a 4 rather than 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?

The most important instruction ('Call this first') is front-loaded, which is good, but the description then restates the same content twice — the dataset/dimension/measure enumeration appears in paragraph one and again nearly verbatim in paragraph two. Roughly half the text is redundant, wasting budget on a body that should be tight.

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. The description covers scope, the ordering constraint relative to write-ahead report definition tools, and the account-level disabled state — everything an agent needs to call it correctly or route the user appropriately.

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 merchant_id (scoping/auth caveat) and conversation_id (must be echoed unchanged, do not invent, no parallel calls) are fully documented in the schema. The description adds nothing about parameters, 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 (list report datasets and fields) and immediately scopes it to 'what a custom report can use on this account', which separates it from list_reports, get_report, and preview_report. The enumerated dataset types make the scope concrete.

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 ordering ('Call this first') and a hard precondition ('a report definition may only use ids listed here' / 'ids not listed here are refused'), plus a when-not case: while custom reports are off, the tool fails with 403 and the agent should not retry. This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add context — and it does, disclosing the ordering contract ('Pinned first, then most recently updated') and the access model ('reports you can open'). It stops short of describing pagination or result-size limits, which would matter for a list endpoint with openWorldHint=true.

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

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

The scoping information is front-loaded, but the two sentences substantially duplicate each other: 'yours, shared with you' and 'JobMojito templates' appear verbatim in both, and the second sentence re-states the whole listing scope before adding the ordering detail. Roughly a sentence of redundancy for a short 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-field explanation is not strictly required, and the description still adds the ordering semantics that the output schema would not convey. The gaps — no pagination or result-limit behavior — are minor given full annotation and schema coverage.

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 (scope enum, merchant_id permissions, conversation_id protocol) are fully documented in the schema itself. The description only echoes the scope concept in prose ('yours, shared with you, templates') without adding format or constraint detail beyond it. 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 ('List custom reports') and narrows scope precisely: reports you own, reports shared with you, and JobMojito templates. It also enumerates the returned fields (id, title, visibility, access, version), which separates it cleanly from get_report (single item), list_report_fields (field metadata) and run_report (execution).

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 scope enumeration in the schema and by 'reports you can open,' but the description never says when to prefer this over get_report, list_report_fields, preview_report or run_report. No explicit exclusions or prerequisites are given, so the agent must infer routing from the name alone.

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

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

Annotations already 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond them: nothing is persisted, validation is against the catalogue, and failure returns ok=false / a 422 naming the offending block and field plus the valid ids. Minor inconsistency in presenting the failure as both 'ok=false' and 'a 422', but not a contradiction of 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?

The lead sentence is front-loaded and useful, but the second paragraph is a near-verbatim restatement of the first (validate against catalogue, run, nothing stored, use before create/update, error names the field). Roughly half the text earns no new information, which is a clear structural waste even though the total length is modest.

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

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

With an output schema present, the description needn't explain return values, and annotations cover the safety profile; combined with the purpose, the pre-flight guidance and the error semantics, an agent has enough to call it correctly. It could still mention that the definition's dataset/field/measure ids must come from the catalogue, which lives only in the nested schema description.

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 80% and the nested definition schema is heavily self-documented (block types, measures, filters, grain), so the baseline is 3. The description adds no parameter-level meaning — it never mentions block_id (run a single block), merchant_id scoping, or the required conversation_id handshake, all of which are only explained 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+resource combination — validate a report definition and run it without saving anything — and explicitly frames it as a pre-flight step ahead of create_report / update_report. An agent can distinguish it from the other report siblings (create_report, update_report) 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 gives a clear when-to-use rule: 'Use it before create_report / update_report', which is exactly the decision an agent faces when it has a candidate definition. It does not, however, state when NOT to use it (e.g. to read an already-saved report, where get_report/run_report would apply), so the guidance stops just short of full routing.

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?

Adds real context beyond the annotations: the report becomes a support conversation answered by support, the identity/e-mail and company/ids attached, the 5-per-24h quota, the required auth session type, and the instruction to confirm wording with the user first. Annotations already flag non-idempotent/destructive/open-world, so the description earns credit for the auth, quota and side-effect detail rather than restating safety hints.

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 body contains two near-verbatim paragraphs saying the same thing (opens a support conversation, from the user's e-mail, with company and ids, support answers there, 5/day cap). Roughly half the text is redundant restatement, which dilutes a description that is otherwise 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 explained. The description covers side effects, auth requirements, quota, and user-confirmation duty for a mutation tool; only the conversation_id continuation behavior is left entirely to the schema.

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

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

Schema description coverage is 100%, so all four parameters (including the detailed conversation_id protocol and the description content) are already documented in the schema. The description only loosely gestures at 'the interview or result ids given' and never mentions conversation_id, so it adds little beyond what the schema provides. 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?

States a specific verb and resource: 'Report a technical problem to JobMojito support', and clarifies the mechanism (opens a support conversation from the user's e-mail). It implicitly separates itself from submit_feature_request via the technical-problem framing, but never names that sibling explicitly, so differentiation relies on 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 concrete preconditions: 'Confirm the wording with the user first', a rate limit ('at most 5 a day'), and the required token/role ('merchant, merchant owner or admin'). It does not say when to prefer this over submit_feature_request, which is the closest alternative in the sibling list.

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 cover readOnly/idempotent/non-destructive, but the description adds real behavioral context: per-block failure isolation (ok=false with error while other blocks still return data), a 500-row-per-block cap, and the filter precedence chain (report defaults → saved filters → `filters`). The 'decision-support material for a human reviewer' caveat is a useful framing signal about how much weight to put on the numbers.

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 definition repeats itself: the opening line and the second paragraph both say 'run a saved report and return its rows,' and the 500-row limit is stated twice. Front-loading the verb and resource is good, but roughly a third of the text is restatement rather than new 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 and every parameter documented, the description only needs to cover execution semantics, and it does: partial failure, row caps, filter precedence. Nothing essential for a correct invocation is missing, though the lack of sibling routing is the one remaining hole.

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 baseline is 3; the description earns above that by documenting filter merge order and the per-run-only scope of `filters`, which the schema does not state. It does not add anything for `conversation_id` or `merchant_id` beyond what the schema already says.

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: run a saved custom report and return each block's rows, with the aggregation level and 500-row cap made explicit. It is distinguishable from get_report/preview_report/create_report by the 'run and return rows' framing, though it never names those siblings to draw the boundary 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 implied rather than prescribed: `draft` hints at editing permission, `block_id` at partial runs, and `filters` at per-run overrides. There is no explicit guidance on when to use run_report versus preview_report, get_report, or generate_interview_report, so an agent must infer the routing from names alone.

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

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

Annotations already 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 declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the agent knows this is a repeatable mutation. The description adds that it also manages the embed key and requires status-or-embed to be supplied, but it never says what 'deleted' actually destroys or whether that transition is recoverable — the one piece of context annotations can't convey.

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

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

Two sentences, front-loaded with the core action and capped with the calling constraint. There is minor redundancy between 'Change the state' and 'Changes the lifecycle status', but no 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 and parameters are fully documented, so the description need not cover returns. It is nonetheless incomplete for a destructive mutation: no differentiation from `update_interview`, no permission/confirmation expectations, and the illustrative examples '(e.g. open, closed)' do not match the actual enum values (draft/active/archived/deleted/preparing/completed).

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

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

Schema description coverage is 100%, and the `is_embedded` and `conversation_id` entries are already richly documented in the schema, so the schema does the heavy lifting. The description only restates the status value list and the 'at least one of status/is_embedded' rule, adding little beyond structured data — 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?

Specific verb (change state) plus resource (interview/position) and an enumeration of the lifecycle values it can set, so the agent knows it is a status/embed-key mutation rather than a general edit. It does not, however, distinguish itself from the sibling `update_interview`, which an agent must otherwise infer.

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 only real guidance is the precondition 'Provide at least one of `status` or `is_embedded`', which tells the agent how to call it but not when to prefer it over `update_interview` or how to sequence it after `create_interview`/`get_interview_definition`. 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 cover the mutation/open-world/non-idempotent profile, but the description adds real context beyond them: the post is public under the user's name, the company is not named, others can vote, and there is a hard rate limit of 5 per 24 hours. It omits what happens on failure or whether a submission can be edited/withdrawn.

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-duplicate paragraphs: both restate that a request is sent to the product team, posted publicly under the user's name, that the company is not named, and the 5/day limit. The duplication wastes tokens even though the second paragraph adds the auth requirement and voting detail.

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 description covers auth requirements, rate limits, content restrictions and public visibility. The main gap is the lack of explicit routing guidance against sibling tools, but for a single-purpose submission tool this is largely 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%, including constraints on title/description and the conversation_id handling, so the schema does the heavy lifting. The description's 'write a short title and a description of the need and why (no candidate data or company names)' only restates constraints already in the schema, 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 and resource ('Send a feature request to the JobMojito product team') and distinguishes itself from siblings like report_technical_issue by naming the destination (public feature request board). An agent can tell what it does 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?

Gives clear usage context: confirm wording with the user before submitting, keep the title short, describe the need and why. It does not explicitly name an alternative tool or state when NOT to use it (e.g., vs. report_technical_issue), so it falls short of the top tier.

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 the safety profile is covered. The description adds real behavioral context on top: partial-write semantics, that null clears nullable fields, that `content_md: null` restores the default grid, and that `translations: null` removes every language version.

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 is a well front-loaded summary, but the second paragraph restates the same field list almost verbatim, which is genuine redundancy rather than added value. The structure is openable and readable, but a third of the text is duplicated 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?

For a 13-parameter mutation tool with an output schema and rich annotations, the description is reasonably complete: it covers partial-update semantics and null-clearing behavior, which are the main risks an agent must understand. It stops short of stating permission/auth requirements beyond the row-level-security note buried in the `visibility` enum.

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 13 parameters in depth; the description's parameter references (`tags_interview_set_filter`, `tags_sub`, `content_md`, `translations`) merely name fields already fully described. Baseline 3 applies since the schema does the heavy lifting.

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

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

The description names a specific verb and resource ("Update a coaching catalogue directory") and enumerates exactly which aspects can be changed — rename, session filter, sub-directory order, Markdown page, translations. It is unambiguously an update tool rather than create_catalogue_directory or get_catalogue_directory, though it never explicitly names those siblings.

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

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

It gives solid context for what kinds of edits the tool performs and the partial-update model ("Only the fields you send are changed"), but offers no when-not-to-use guidance and never routes the agent to an alternative such as the admin catalogue editor referenced only inside the `id` schema field.

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