JobMojito

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

The annotations already communicate mutation and non-read-only behavior; the description adds genuinely useful behavioral detail such as the id becoming the URL segment and being unchangeable afterwards. It also explains that setting content_md replaces the default grid, which is meaningful beyond what annotations supply. No contradiction with annotations was found.

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 overlapping paragraphs that restate the same core facts almost identically. The '[Coaching catalogue]' prefix and 'Coaching-platform feature' line add little, and the important immutability warning is buried at the end after the duplicate explanation. A single compact paragraph would be more effective.

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 tool, the description does a good job of explaining the overall role of a catalogue directory and how the key fields fit together. Combined with the fully detailed 100%-coverage input schema and an output schema, it provides enough context for an agent to select and invoke the tool correctly, though it could be tighter.

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 adds real extra meaning by warning that the id cannot be changed after creation, which directly affects how an agent should choose and validate the id field. It also frames the relationship between tags_sub, tags_interview_set_filter, and content_md more conceptually than the schema alone.

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

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

The description opens with 'Creates a directory (page) in the coaching portal catalogue', which names a specific verb and resource. It also clarifies that the directory can nest children, filter sessions, and carry custom Markdown, so an agent can distinguish it from create_interview/create_persona and from read/update catalogue tools.

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

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

The tool is clearly positioned as the way to create a new coaching catalogue directory, with no ambiguity about whether this is a listing or reading tool. It does not explicitly name update_catalogue_directory as the alternative for modifying existing directories, but the creation context is clear and no misleading exclusions are present.

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 readOnlyHint=false, so the description does not need to restate that this is a mutating creation. It adds useful context about AI generation of description/questions/expectations, auto-provisioned steps, and optional embed key. However, it doesn't detail reversible behavior or effects on existing resources, though creation tools are generally understood.

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 repeats itself — the first sentence and the second block both say 'creates a new interview... generates questions... provisions steps'. The first paragraph is also awkwardly phrased and the modality note is partially redundant with the schema's own parameter descriptions. It could be compacted to one focused paragraph.

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, 100% parameter coverage, and an annotations block, the description has a lighter burden. It covers core creation scope, AI generation side effects, and embed key provisioning. But it omits clear guidance distinguishing it from create_interview_from_questions and doesn't mention return semantics beyond the annotation context.

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% with 46 richly described parameters, so the description doesn't need to carry parameter semantics. The description adds a high-level pointer to the template ID's modality effect. Baseline 3 is appropriate given 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 states it creates a new interview and auto-generates the question sequence, which is a specific verb+resource. However, it's somewhat redundant and unclear about its relationship to sibling create_interview_from_questions, and the extra detail about modality/embed keys is muddled. It is distinguishable but not sharply.

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 mentions `list_avatars` for modality and implies AI-generated defaults, providing some context. But it doesn't explicitly say when to use this tool vs create_interview_from_questions vs update_interview — a key alternative is missing, so usage boundaries are 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 mark the tool as non-read-only and potentially destructive. The description adds meaningful behavioral context beyond that: it builds default and generated steps, optionally activates the interview, and optionally creates an embed key. It does not contradict the annotations, and it gives useful side-effect awareness without repeating structured annotation data.

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 short and front-loaded, but the first and second sentences are largely redundant: both essentially say 'create a new interview from an explicit array of questions.' The second sentence adds genuine value with the side-effect details, but the redundancy prevents a higher 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?

Given the tool's high complexity — 44 parameters, nested question definitions, and an output schema — the description provides an adequate high-level overview. It covers the core creation flow and key optional side effects, and the extensive schema and existing output schema compensate for any additional detail an agent might want.

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

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

Schema description coverage is 100% across 44 parameters, so the schema carries the semantic burden. The description adds only high-level context about questions and generated steps, which maps to the questions parameter but does not meaningfully improve parameter-level understanding beyond the schema.

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

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

The description clearly states the tool's function: creating a new interview definition from a caller-provided array of questions. It also differentiates from the sibling create_interview by emphasizing the explicit 'array of questions' mechanism rather than generic interview creation.

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 usage context: use this tool when you already have an explicit list of questions and want an interview created from them. However, it does not explicitly name alternatives like create_interview, nor does it state when-not-to-use it, so the guidance is implied rather than direct.

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 indicate mutation (readOnlyHint=false, destructiveHint=true), but the description adds substantial behavioral context: the dual-product nature, session flow (welcome → opening line → free-form → closing), default 'Hello' opener, and the consequence of omitting persona_avatar_progress (unstable concession behavior). No contradiction with annotations.

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

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

The text is long but well-structured with bolded headings, bullet lists, and a front-loaded portal warning. Some redundancy exists—the free-form contrast is stated twice and the opening_line default is repeated—but given the tool's 31 parameters and complexity, the length is largely justified.

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 31-parameter tool with a rich schema and output schema, the description covers the non-obvious product split, session flow, defaults, scoring scale, and prompt-field semantics. It complements the schema rather than repeating it, making it a fully sufficient guide 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 has 100% parameter coverage, providing a baseline of 3, but the description adds significant meaning by grouping the four persona prompts into a coherent division, highlighting portal as the primary decision, and explaining how opening_line, welcome_message, and candidate_expectations fit the session flow. This goes far beyond the schema descriptions.

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?

Description opens with a specific verb and resource: 'Create a role-play persona', immediately contrasted with 'a scored Q&A interview', which distinguishes it from sibling tools like create_interview and create_interview_from_questions. It further specifies the persona role fields as the configuration, reinforcing its unique 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?

Explicitly instructs 'FIRST DECIDE portal' and defines when to use the interview portal ('ASSESS or SCREEN candidates... anything a recruiter runs') versus the coaching portal, warning that the default is coaching, not recruiting. This gives clear when-to-use and when-not-to-use guidance with named 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?

Discloses that PDF can be persisted and returns a signed URL, and that translation costs 0.1 credit per result. Annotations indicate destructiveHint=true and idempotentHint=true, which align with the described behavior. Adds context beyond annotations without contradiction, though it could clarify the idempotent nature more explicitly.

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 succinct with two paragraphs: the first establishes purpose and context, the second details the two usage paths and export formats. Every sentence carries value, with no redundant or filler 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?

Covers the essential aspects: purpose, input parameters, and key options. Given the complexity (nested object with many flags), the description relies on the schema for sub-property details, which is acceptable. The existence of an output schema reduces the need to describe return values, though the description could briefly mention that reports are generated synchronously or any limitations.

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

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

The description adds meaningful context for the ID parameters and export types by explaining their relationship (single vs. combined report) and the three output formats. While the nested export_features_result object is not elaborated in the description, its sub-properties are well-documented in the schema. The description compensates for the 40% schema coverage by clarifying the core 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 clearly states the tool generates interview result reports in HTML/PDF/JSON formats for completed interviews, serving as decision-support material. It specifies the target audience (human reviewer) and distinguishes from siblings by focusing on report generation rather than creation, listing, or 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?

Provides explicit instruction to provide either interview_result_id for a single result or interview_result_ids for a combined multi-result report. However, it does not explicitly state when not to use this tool or mention alternatives like get_interview_result_details for raw data, though the context of 'completed interview' implies applicable scenarios.

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 provide destructiveHint=true and readOnlyHint=false, and the description adds that the URL is signed and public. However, it does not elaborate on side effects (e.g., token expiration, invalidation of previous URLs) or required permissions beyond what the schema indicates.

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 brief and front-loaded with a category tag and two sentences. It is efficient, though the '[Interviews]' bracket prefix is somewhat 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?

For a tool with six parameters, one required enum, and an output schema, the description covers the core idea but lacks guidance on selecting the appropriate 'type' value. An agent would need to infer from the schema descriptions, which are present but not synthesized in the tool 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 coverage is 100% with each parameter described. The description reinforces that required IDs depend on 'type', but adds little beyond the schema's parameter descriptions. Baseline 3 is appropriate.

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

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

The description clearly states it generates a signed public URL/token for an existing interview, profile, or result. The verb 'generate' and resource 'interview URL/token' are specific, and the tool's function is distinct from sibling tools like create_interview or list_interviews.

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 usage for generating shareable links for existing objects, but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusionary guidance or conditions like when not to use it.

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

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

The description goes well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing the critical behavior that `content_md`, `tags_sub`, and `tags_interview_set_filter` are replaced wholesale on update, so reading first is necessary to avoid overwriting. It also clarifies that the read returns resolved sub-directories and matched sessions, not just the directory's own metadata. There is no contradiction with the read-only annotations.

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

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

The description is noticeably duplicated: the first bracketed paragraph and the following paragraph both state nearly identical information about reading a directory, its returned fields, and the wholesale replacement warning. This wastes space and muddles the front-loading. A single, tight summary would be more concise and easier for an agent to parse.

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 that this is a read-only get operation with an output schema, described parameters, and the full behavioral nuance about update replacement, the description covers everything needed to call the tool correctly. The $merchant_id$ scoping is already documented in the schema. Any redundancy in the description does not cause content to be omitted.

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

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

The schema already has 100% parameter coverage, including examples and permission notes for `merchant_id`. The description adds no extra meaning for the parameters themselves, mentioning only the returned fields rather than the input `id` or `merchant_id`. With full schema coverage, 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?

The description uses a specific verb and resource — 'Reads one catalogue directory in full' — and enumerates exactly what is returned: settings, `content_md`, sub-directories, and the sessions matched by the tag filter. This clearly differentiates it from the sibling `list_catalogue_directories` because it targets a single directory and from `update_catalogue_directory` because it is a read operation.

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

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

The description explicitly states when to use this tool: 'Read a directory before updating it' and explains why — the fields are 'replaced wholesale' by updates. It also gives the verification use case of checking whether a session's tags place it in a directory. However, it does not name the alternative tool to use when a list is needed or specify when not to use this tool.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds context: auto-fetches Markdown for developer docs, truncates based on max_chars, and domain restrictions. This provides value beyond annotations.

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

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

The description is four concise sentences, each adding distinct information: purpose, URL source, special behavior for developer docs, and domain restrictions. No fluff, front-loaded with primary purpose.

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 the tool's simplicity, the description covers essential context: what it does, how to get the URL, automatic Markdown handling, and domain restrictions. It does not detail error behavior or output format, but output schema exists and annotations cover safety.

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 descriptions cover both parameters (100% coverage), so baseline is 3. The description adds meaning by specifying that the URL must come from search_documentation and that only certain domains are allowed, which aids correct usage.

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

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

The description clearly states the tool fetches the full content of a single documentation page (specific verb+resource). It distinguishes from sibling tools like search_documentation by specifying that it accepts URLs from that tool and only allows certain domains.

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

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

The description explicitly says to use a URL from search_documentation and restricts usage to specific domains. It implies when to use (after searching) but does not explicitly state when not to use or mention alternatives beyond search_documentation.

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 indicate this is read-only, idempotent, and non-destructive. The description adds useful context: returns include `calc_definition_json`, metadata, and question ids should be preserved for round-tripping. It also discloses row-level security restrictions, which is valuable beyond 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 description is front-loaded with the core purpose and workflow, but it has redundant phrasing: both paragraphs repeat the same-format round-trip point using different names. A tighter version would be just as clear with less 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?

With a full schema covering the only parameter, rich annotations, and an output schema, the description still adds all necessary behavioral context: resolved ID types, returned fields, workflow usage, and row-level security. An agent has enough information to call and use this tool correctly.

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

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

Schema coverage is 100%, and the schema already explains that `position_id` can be an interview or a position definition id. The description reinforces the round-trip purpose but does not add further parameter details, so the baseline of 3 is appropriate.

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

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

The description clearly states that the tool retrieves the full definition/configuration of an interview, including its ordered `questions` array. It also distinguishes the read operation from create/update sibling tools by explicitly tying the output into a round-trip workflow.

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 specific usage context: read the definition, modify the questions array, and send it to update_interview. It also clarifies that `position_id` can be either an interview-definition id or a position id. However, it does not explicitly state when to use list_interviews or another sibling for lighter-weight reads.

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, describing the safety profile. The description adds context: scores are 'assistive output for a human reviewer' and recording URLs are optional. This goes beyond annotations without contradiction.

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

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

The description is concise with four sentences, front-loading the main purpose. The use of '[Results]' as a tag adds categorization. However, the structure is slightly fragmented; grouping optional details more tightly could improve readability.

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

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

Given the tool's simplicity, presence of an output schema, and comprehensive annotations, the description covers key aspects: transcript, scores, AI assessment, and optional recordings. No further details (e.g., prerequisites, permissions) are necessary for this read-only 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?

Both parameters (interview_result_id, get_signed_recordings) have clear descriptions in the input schema (100% coverage). The tool description mentions 'Optionally attaches signed recording URLs' but does not add new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states 'Get full interview result details including transcript and scores' and mentions optionally attaching recording URLs. This distinguishes it from sibling tools like list_interview_results which returns a list without details. The verb 'get' and resource 'interview result details' are specific and unambiguous.

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

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

The description implies usage when full details are needed (e.g., 'Get full interview result details') but does not explicitly state when to use this over alternatives like list_interview_results. No exclusions or 'when not to use' guidance is 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint: false), the description adds critical behavioral details: pagination cap at 1000 records per page, only non-zero counts returned (implicit zero padding), and optional drilling to interview. This provides valuable context for an AI agent.

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 clear and front-loaded with purpose, but it is a single paragraph that could be slightly more structured. It is concise, but the note about zero padding could be separated for clarity.

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

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

Given the tool's complexity (6 parameters, optional drilling, pagination) and the presence of an output schema, the description adequately covers usage scope, pagination behavior, and zero-padding note. It omits explicit read-only mention, but annotations cover that.

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

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

The input schema covers all six parameters with descriptions, and the description adds minimal extra meaning beyond schema. It mentions scoping and drilling, but these are already in the schema descriptions. Baseline 3 is appropriate given 100% 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?

The description clearly states the tool retrieves daily event analytics for a merchant using specific verbs and resources ('Get the merchant's daily event analytics'). It distinguishes itself from sibling tools like get_merchant_credit_usage and get_merchant_status by focusing on event-count time-series, making the purpose unambiguous.

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

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

The description explains when to use the tool, including scoping to token merchant or merchant_id override and optional drilling to an interview. However, it does not explicitly state when not to use it or compare with alternatives, which would raise the score to 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 indicate read-only, idempotent, non-destructive behavior. The description adds that results are ordered most recent first and capped at 1000 records per page, which are useful behavioral details. No contradiction with annotations.

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

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

The description is concise (about 5 lines), front-loaded with the main purpose, and every sentence adds value. No redundancy or fluff.

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

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

Given the annotations (readOnlyHint, idempotentHint, etc.) and the presence of an output schema, the description provides sufficient context: it explains the return format (ledger with credit_amount), ordering, pagination limit, and parameter behavior. It is complete for a read-only 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?

The description adds significant meaning beyond the input schema: it explains the merchant_id scope permission, and the interview_id parameter's dual behavior (detecting interview vs. position and combining credits accordingly). Schema coverage is 100%, but the description enriches understanding.

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

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

The description clearly states the tool returns a per-event credit-usage ledger for a merchant, listing billable analytics events that consumed credits. It distinguishes from siblings like get_merchant_analytics and get_merchant_status by focusing on detailed credit consumption events rather than aggregated analytics or status.

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 explains scoping (token's merchant or merchant_id override for admins) and drilling down via interview_id or position_id. However, it does not explicitly compare to sibling tools or state when to prefer this tool over alternatives, leaving some inference required.

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

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

Annotations include readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that the tool echoes caller's profile_id and default_merchant_id, and clarifies authorization boundaries for the merchant_id parameter. No contradictions with annotations.

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

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

The description is two sentences: a high-level summary followed by a detailed list of components. It is front-loaded with the purpose and succinctly expands without unnecessary words.

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

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

Given the presence of an output schema, the description need not cover return values. It fully describes all components of the snapshot and the caller info echo, making it complete for a read-only, idempotent 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% with description for the only parameter (merchant_id). The tool description adds valuable context about who can use the override (admins/sub-merchant operators), improving clarity beyond the schema.

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

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

The description clearly states it retrieves a 'merchant status snapshot' and lists specific components like credit balances, subscription, pending-work counts, etc. It distinguishes from sibling tools such as 'get_merchant_analytics' and 'get_merchant_credit_usage' by detailing the unique fields included.

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 explains scope: default to token's merchant, with optional merchant_id for admins/sub-merchant operators. While it doesn't explicitly name alternatives, it provides clear context on when to use the optional parameter and who can use it.

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 indicate readOnlyHint, idempotentHint, destructiveHint. The description adds useful behavioral context: it renders a UI, is interactive, and instructs the agent to pass merchant_id on subsequent calls. No contradictions.

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

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

The description is concise and front-loaded with the main purpose. Every sentence adds value, and it efficiently conveys usage instructions.

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 simple tool with no parameters and no output schema, the description is complete. It explains the action, when to use it, and the expected behavior, including integration with other 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?

There are no parameters (empty input schema), so baseline is 4. The description correctly handles this by not needing to add parameter info.

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

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

The description clearly states the tool's purpose: 'Show the interactive JobMojito merchant picker (UI).' It uses a specific verb and resource, and the context differentiates it from sibling tools like list_my_merchants.

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

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

Explicit guidance is provided: 'ALWAYS call this when the user wants to choose, switch, or set a merchant...' and includes what not to do ('Do NOT list merchants as text...'). It also instructs the agent to stop and wait for the user's selection.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior; the description adds genuinely useful behavior beyond that, such as default page size of 15, the 1000-record cap, scoping to the token's merchant or `merchant_id`, and the legacy-template caveat. No statement contradicts 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 text is dense and front-loaded with the most decision-relevant information, and every sentence carries some useful content. It loses a point only for a slight redundancy where the pagination/count behavior is described in both the first paragraph ('returns 15 at a time') and the second ('Capped at 1000 records per page').

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 the rich input schema, output schema, and strong annotations, the description covers the remaining needed context: how to pick the correct template, what legacy types mean, how pagination works, and how merchant scoping applies. An agent can safely and correctly call this tool without additional documentation.

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 materially enriches the `type` parameter by mapping each enum value to a concrete interview modality. It also gives practical meaning to `offset`, `filter_text`, and `merchant_id` through pagination and scoping guidance, which goes beyond the schema without restating every field.

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 operation ('List available avatar/voice templates') and a specific resource, then explains what returned items mean. It clearly distinguishes itself from sibling tools by defining how `type` maps to interview modality, so an agent knows this is for template selection, not for listing interviews or candidates.

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 explicitly tells the agent to choose the template whose `type` matches the intended experience and that the returned `id` becomes `interview_template_id` for create-interview tools. It also provides concrete operating guidance: paginate with `offset` while `pagination.has_more` is true, narrow with `type`/`filter_text`, and avoid legacy `offline_elai`/`offline_synthesia` types for new interviews.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds useful behavioral details: pagination with a 1000-record cap, scoping to merchant, and optional merchant_id override. No contradictions with annotations.

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

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

The description is concise with three short sentences, no redundant information. It is front-loaded with the core purpose. Could be slightly more structured, but no wasted words.

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

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

Given the presence of an output schema, the description adequately covers the tool's behavior (pagination, scoping, cap). It could mention filtering options, but the schema handles that. Completeness is sufficient for an AI agent.

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 descriptions cover all 8 parameters (100% coverage), so the description's contribution is minimal. It mentions pagination cap but does not explain individual parameters beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the merchant's candidates, with pagination and scoping to the token's merchant or an override. The verb 'list' and resource 'candidates' are explicit, and there is no sibling tool with a similar purpose to cause confusion.

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

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

The description provides clear context on when to use the tool (listing candidates) and constraints like scoping and pagination limits. However, it does not explicitly state alternatives or when not to use it, though no direct alternatives exist among siblings.

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

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

Given the annotations already declare readOnlyHint and idempotentHint, the description adds useful behavioral context beyond the annotations: it states the list is paginated, includes public directories unless include_public=false, and notes that the custom Markdown page is excluded. It also describes how 'is_start_directory' marks the catalogue's default page, which is not in 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 description contains two paragraphs that largely repeat the same information with slightly different wording. The first paragraph is a concise summary, while the second re-states the same points (list scope, use cases, custom Markdown exclusion). This redundancy wastes tokens and violates the 'every sentence should earn its place' principle.

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?

The tool has 9 parameters and some complexity, but the description orients the user well: it explains the result scope, typical use cases, the exclusion of the custom Markdown page, and pagination. The output schema exists, so return values are covered there. Despite not detailing every filter, the schema covers them, and the description provides enough context for effective selection and 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?

The schema has 100% parameter description coverage, so the baseline is 3. The description adds extra meaning for key parameters: it explains that include_public controls whether public directories are included ('unless you set include_public=false') and elaborates on parent_tag usage ('walk the tree with parent_tag'). This goes beyond the schema's basic field descriptions.

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

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

The description clearly states the tool's purpose: 'List the coaching-catalogue directories you can see' and distinguishes it from the sibling tool get_catalogue_directory by noting the custom Markdown page is not included and should be read with get_catalogue_directory. It also specifies the scope (merchant's own plus public) and typical use cases.

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

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

The description explicitly tells when to use this tool ('Start here to find a directory id, to pick a parent for a new one, or to walk the tree with parent_tag') and provides an alternative for a specific case: 'The custom Markdown page is not included — read it with get_catalogue_directory.' This gives clear context and exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: pagination cap of 1000 records, scoping rules, and that it's the admin-portal results list.

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

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

The description is concise, front-loaded with purpose, and uses two short paragraphs. Every sentence adds value without unnecessary elaboration.

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 the complexity (12 parameters, output schema exists), the description covers the purpose, pagination, scoping, and cap. It could mention the default type or sort order, but the output schema compensates. Overall adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool-level description does not add significant per-parameter meaning beyond what the schema provides. It mentions the 1000 cap, which is reflected in the limit parameter.

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

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

The description clearly states the action (list), resource (interview results), and scope (merchant's, admin-portal). It differentiates from siblings like get_interview_result_details and list_candidates by focusing on a paginated list of 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?

The description implicitly indicates when to use this tool (to list results, paginated, scoped) but does not explicitly state when not to use it or suggest alternatives. The context of scoping is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: paginated list, capped at 1000 records, scoped to merchant, and optional merchant_id override for admins. No contradictions.

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

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

The description is concise with two sentences plus a header. It front-loads the action and every sentence adds value without redundancy.

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

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

Given the tool's complexity (9 params, many siblings, output schema exists), the description covers the main purpose, scoping, pagination cap, and merchant override. Output details are handled by the existing output 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?

With 100% schema description coverage, baseline is 3. The description adds value by explaining merchant_id scoping and the 1000 cap, which relate to parameters not fully covered in schema descriptions.

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

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

The description clearly states 'List the merchant's interview definitions' and 'Paginated list of a merchant's interview definitions'. It identifies the verb (list) and resource (interview definitions), distinguishing it from sibling tools like get_interview_definition (singular) and create_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?

The description mentions scoping to token's merchant or merchant_id override and a cap of 1000 records per page, providing usage context. However, it does not explicitly state when to use this tool versus alternatives like get_interview_definition or create_interview.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds admin restriction and specifies exact return fields (code, names, flag URL, etc.), adding value beyond annotations.

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

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

Two paragraphs restate similar information, with redundancy. Could be condensed into one sentence with bullet points for fields. Not excessively long but not optimally concise.

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 zero parameters and presence of output schema, the description still adds valuable context (admin requirement, usage of code) and lists return fields. Complete for its purpose.

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?

No parameters, so baseline is 4. Description explains returned fields, though it is somewhat repetitive. Still provides clarity on what is returned.

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?

Clearly states it lists supported platform languages, including specific fields like code, names, and flag URL. Distinct from siblings which are about interviews and personas.

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?

Includes [Admin] prefix indicating intended audience, and mentions using the code in interviews/personas. Lacks explicit when-to-use vs alternatives, but context is sufficient for a simple list tool.

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

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

Annotations already declare readOnlyHint true and destructiveHint false. The description adds behavioral context: it is a fallback, returns own account plus sub-merchants, and advises how to use the result. No contradictions, and the extra context is helpful, though it doesn't detail rate limits or authentication.

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

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

The description is concise, using three sentences that front-load the key purpose ('FALLBACK merchant list') and then efficiently cover usage, return content, and follow-up actions. No unnecessary verbiage.

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 the tool's simplicity (one optional parameter, output schema present), the description is complete: it explains purpose, when to use, what it returns, and how to use the output. The presence of an output schema relieves the need for return value details.

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% with one parameter described. The description does not add new semantic information beyond the schema's parameter description; it merely restates 'sub-merchant name' implicitly. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a fallback merchant list for clients without UI support. It explicitly distinguishes from the interactive picker (jobmojito_configuration) and implies differentiation from list_sub_merchants by indicating it returns both own account and sub-merchants.

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

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

Explicit guidance on when to use (only when client cannot render UI), when not to use (when UI is available, use jobmojito_configuration instead), and what not to do (do not hand-format as text). Also provides usage instructions for the returned merchant IDs.

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 indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details: pagination capped at 1000 records, row-level security, and admin scope, which go beyond annotations.

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

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

Two concise sentences front-load the admin context and purpose, followed by pagination and security details. No unnecessary words.

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

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

With full schema coverage and annotations, the description covers core purpose, pagination cap, and security. Output schema exists, so return values are not needed. Lacks mention of sorting/filtering but schema handles that.

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% with detailed descriptions for all 5 parameters. The description adds minimal new meaning, only reiterating the pagination cap already present in the schema. 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?

The description explicitly states 'List sub-merchants under the merchant account' with a clear verb (list) and resource (sub-merchants). No sibling tool has a similar name, so differentiation is inherent.

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 specifies admin context and row-level security, giving clear usage context. However, it does not explicitly exclude alternative tools or provide when-not guidance, though naming makes it unique.

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

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

The description adds useful behavioral context beyond annotations: it discloses that the operation registers or updates profiles, returns one-time interview URLs, and has different auth requirements. While destructiveHint is true, the description doesn't spell out destructive side effects, but it does not contradict 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 description is two tight sentences with no filler. It front-loads the core operation in the first sentence and adds auth nuance in the second, making it easy for an agent to quickly grasp the tool's purpose.

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 the rich input schema, output schema, and annotations, the description covers the essential operation, return value, and auth requirements. It is complete enough for correct invocation, though it could be slightly stronger by explicitly stating what the destructive hint implies for existing candidate registrations.

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 7 parameters thoroughly. The description reinforces the merchant_id/service-key relationship and the per-user URL return, but does not add significant meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Register users/candidates for a specific interview' and returns their personal interview links. It clearly distinguishes this from sibling tools by emphasizing the registration/update of candidate profiles and the one-time URL output.

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 clear context for when to use the tool: when candidates need to be registered or updated for an interview and per-candidate interview links are needed. It also provides authentication guidance (user JWT vs service key with merchant_id), but does not explicitly name alternatives or when-not-to-use conditions.

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

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

Annotations indicate destructiveHint=true, and the description elaborates on the destructive actions: marking unsuccessful, resetting to draft, and clearing the recruiter decision. This adds context beyond annotations about the specific state changes.

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 purpose, followed by detailed effects. No redundant information. Every sentence adds value.

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

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

The description explains the preconditions (submitted+completed) and the effects. With an output schema present, return values are not needed. It is sufficiently complete for a mutation tool with clear annotations.

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

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

Schema coverage is 100%, and the single parameter 'interview_result_id' is described in the schema. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool reopens a submitted interview result for another attempt. It specifies the action, resource, and effects (marks unsuccessful, resets to draft, clears decision), distinguishing it from siblings like set_interview_state.

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

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

The description provides context on when to use the tool: for submitted (active+completed) interview results. It implies preconditions but does not explicitly mention when not to use or alternatives. This is clear enough for most agents.

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 provide readOnlyHint=true and idempotentHint=true. The description goes beyond by detailing the parallel search across two sources, merging with source labels, and serving as the single entry point. No contradiction with annotations.

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

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

The description is concise with clear structure: purpose, behavior, usage guidance, and a note about subsequent use of `get_documentation`. Bullet points effectively list the two documentation sources. Every sentence contributes meaning without redundancy.

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

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

Given the tool's complexity (search with merging) and the presence of an output schema (confirmed by context), the description fully explains the return format (merged, source-labeled list) and the role of the tool alongside `get_documentation`. It is complete for effective use.

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 the parameters. The description adds value by explaining the content of the 'developer' source (API reference, schemas, etc.) and 'help' source (product guides), enriching understanding of the `source` parameter beyond its enum values.

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

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

The description clearly states the tool searches all JobMojito documentation, merging results from two sources (developer and help) with labels. It distinguishes itself from the sibling tool `get_documentation` by positioning itself as the entry point and advising subsequent use of `get_documentation` for full pages.

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 tells when to use the tool: 'Use this whenever you need to understand how a feature, endpoint, field, or workflow works — including before calling an action tool you're unsure about.' It also clarifies that the user does not need to choose a source or call a separate tool because it handles both sources in parallel.

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

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

The description adds behavioral context beyond annotations: it explains that the embed key is managed via is_embedded, and lists all possible statuses including 'deleted' (destructive). However, it does not mention irreversible effects of deletion or behavior when both parameters are provided.

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

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

The description is two sentences: the first front-loads the core purpose, the second adds detail. No unnecessary words, efficient structure.

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 the presence of annotations, full schema coverage, and an output schema, the description covers the main behaviors and parameter constraints. It lacks information about side effects (e.g., reversible? error conditions?) but is largely complete for the tool's complexity.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by clarifying the constraint 'Provide at least one of status or is_embedded' and explaining the purpose of is_embedded (managing embed key), which supplements 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 clearly states the tool changes the lifecycle status of an interview/position and manages its embed key. The examples 'draft, active, archived' give specificity. However, the parenthetical '(e.g. open, closed)' is slightly inconsistent with the listed enum values, causing minor confusion.

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

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

The description provides a parameter usage guideline ('Provide at least one of status or is_embedded') but does not explicitly tell when to use this tool versus siblings like create_interview or list_interviews. The context is implied but not 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?

Given the annotations already declare destructive/idempotent/read-only intent, the description adds valuable behavioral detail: only sent fields are written, null clears a nullable field, list fields replace whole collections, and `content_md` can restore the default page. It does not discuss permissions or broader side effects, but the annotation context lowers that 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 main purpose and partial-update nuance are front-loaded, which is good. However, the first paragraph and second paragraph repeat nearly the same use-case enumeration and partial-update statement, making the description more verbose than necessary.

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

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

For an 11-parameter mutation tool with an output schema, the description covers the essential behavioral nuances an agent needs: partial update, null-clearing semantics, and full replacement semantics for list fields. The remaining details live in the schema and parameter descriptions, so the tool is adequately specified.

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 each parameter is already well documented. The description references several fields by name and maps them to intents, but it adds no genuinely new semantics beyond what the schema already provides.

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

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

Clearly specifies the verb `update` and the resource (`coaching catalogue directory`), and enumerates concrete actions: rename, change the session filter, reorder sub-directories, or author custom Markdown. This distinguishes it from sibling tools like create/get/list catalogue directories.

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 clearly frames this as modifying an existing directory and explains partial-update semantics, which tells the agent when this tool is appropriate. It does not explicitly contrast with create/list alternatives, so it stops short of a 5.

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

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

The description goes well beyond the annotations: it states that only fields present in the payload are written, explains the diff behavior with unlink/recreate semantics, warns that nothing is ever fully deleted, describes active-template constraints, and clarifies that language and step-based content are immutable. It is fully consistent with the `destructiveHint: true`, `idempotentHint: true`, and `readOnlyHint: false` annotations.

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

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

The description is front-loaded and logically organized, but it repeats itself: the first paragraph and the second paragraph both explain the 'only fields you send' rule, the 'omit questions' behavior, and the constraints on welcome/thank-you and language. The content is extremely valuable, but it could be condensed by roughly a third without losing information.

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

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

For a 40-parameter tool with an output schema and rich annotations, the description covers the critical edge cases: question diffing, active-interview restrictions, avatar template interactions, null-clearing behavior, language immutability, position vs interview field restrictions, and idempotent resending. No essential context for correctly calling this tool is missing.

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

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

The input schema already documents all 40 parameters, so the baseline is high. The prose still adds value beyond the schema by explaining the global partial-update contract, the complete-list/diff behavior for `questions`, the restricted field set for multi-stage positions (422 for interview-only fields), and the catalogue mapping of `tags`. This is more than minimal but not exhaustive per-parameter detail, since the schema handles that.

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

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

The description states a specific verb and resource: 'Update the configuration of an existing interview/position', and enumerates the kinds of settings that can be changed (name, description, avatar template, recording, scoring, tags, questions). It distinguishes the tool from its creation-oriented siblings by emphasizing it updates existing definitions, and it explicitly scopes interview vs position behavior.

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 concrete when-to-use guidance: omit `questions` to leave them untouched, read the interview first and resend the full list to edit questions, set active offline-template interviews back to draft before changing questions, and create a new interview if the language needs to change. It also states alternatives, such as updating multi-stage position interview stages individually, and tells the agent what is not handled by this endpoint.

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 indicate destructiveHint=true (modifies data). The description adds that uploading queues the document for processing, implying asynchronous behavior. However, it does not detail what happens after processing, whether overwriting occurs, or error scenarios. The description adds some context beyond annotations but lacks depth.

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, front-loaded with the purpose, and provides necessary details succinctly. It is slightly verbose in repeating file formats but overall efficient. No unnecessary sentences.

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 that an output schema exists (return values are handled separately), the tool description covers the main behavior: uploading, queuing, and accepted formats. It lacks details about processing time, error handling, or file size limits, but annotations and schema mitigate some gaps. For a 4-parameter tool, it is fairly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the file parameter can be binary or base64 depending on Content-Type, and that the name falls back to the uploaded file name for multipart. This clarifies parameter usage beyond the schema.

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

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

The title and description clearly state that the tool uploads and processes a knowledge base document. It uses specific verbs (upload, process) and identifies the resource (knowledge base document), distinguishing it from sibling tools focused on interviews, personas, and merchants.

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 explains that the tool accepts file as multipart/form-data or JSON, and mentions queuing for processing. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide prerequisites (e.g., store must exist) or exclusion cases. Nonetheless, no direct sibling tool performs similar uploading, so the guidance is adequate.

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