JobMojito

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

The annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false. The description adds important behavioral context: the id becomes the immutable catalogue URL segment, and content_md can replace the default grid layout. These details go beyond the annotations without contradicting them.

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

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

The description contains two paragraphs that largely repeat the same information: 'Create a directory...' and the main features (nests, lists sessions, custom markdown) appear twice. While not overly long, the redundancy means not every sentence earns its place.

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

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

With 13 parameters and a rich schema, the description provides a solid high-level mental model of how directories work (nesting, session filtering, custom markdown) and warns about id immutability. It does not explain every enum or visibility detail, but those are thoroughly covered in the schema, so the description is sufficiently 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 all parameters are well-documented in structured form. The description adds some overarching context (e.g., id immutability, content_md behavior) but does not significantly enhance per-parameter semantics over the schema, warranting the baseline score.

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 'Create a directory (page) in the coaching portal catalogue' with a specific verb and resource. It distinguishes itself from sibling tools like update_catalogue_directory and get_catalogue_directory by its clear create semantics.

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 context about what a directory is and its core features, making the usage implicitly clear. However, it does not explicitly state when to use this tool versus alternatives or mention any exclusions or prerequisites, leaving the guidance at an implied level.

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=false, destructiveHint=true), the description discloses side effects such as AI generation of description/questions/candidate expectations, provisioning default steps, and optionally provisioning an embed key. It also reveals that interview_template_id sets the modality, adding context not present in the 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?

The description is concise and front-loaded, covering the main purpose and key side effects in two sentences. It is slightly redundant (e.g., 'auto-generate its question sequence' vs 'generates its description, questions and candidate expectations') but remains efficient and readable.

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 (46 parameters, output schema present), the description provides a solid overview: creation, AI generation, default steps, modality, and optional embed key. It does not explain return values, but the output schema covers that. The description is complete enough for an agent to understand the tool's core behavior.

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 a baseline of 3 is appropriate. The description adds one meaningful parameter insight (interview_template_id sets modality) but does not elaborate on other parameters beyond what the schema already provides. The added value over the schema is minimal.

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 and auto-generating its question sequence from position data. It also distinguishes itself from sibling tools like create_interview_from_questions by explicitly mentioning auto-generation and AI-driven content 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 (e.g., auto-generates content, provisions embed keys) but does not explicitly state when to use this tool versus alternatives such as create_interview_from_questions. No direct exclusions or alternative recommendations are provided, making the guidance implicit rather than explicit.

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 states it 'Creates a new interview definition set'—a non-destructive action—but the annotations declare destructiveHint=true. This is a contradiction; the description provides no context to reconcile the destructive hint (e.g., whether it overwrites existing definitions), so it fails to disclose actual behavior beyond the annotation.

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 at two sentences, front-loaded with the core purpose, and contains no filler. Every phrase adds information about what the tool does.

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?

Despite the rich schema and output schema, the description does not explain when to choose this over create_interview, and the destructiveHint contradiction remains unresolved. It also fails to mention any caveats about the interview creation process, so the description is incomplete for such a complex 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 input schema has 100% coverage with detailed descriptions for all 44 parameters. The tool description adds no additional parameter semantics beyond what schema already provides, so the baseline score 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 clearly states the verb 'Create' and identifies the resource: 'a new interview from an explicit array of questions.' It distinguishes this from the sibling create_interview by emphasizing the caller-provided question array, and adds how it builds steps, activates, and creates embed keys.

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 this tool is for creating interviews when you have an explicit array of questions, but it does not explicitly state when to use this vs. the sibling create_interview or any other alternative. No exclusions or alternative references are 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 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is known. The description adds meaningful context about the response contents (settings, content_md, sub-directories, matched sessions) and the important update semantics that fields are replaced wholesale, requiring a prior read. This goes beyond the structured annotations.

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

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

The description is notably redundant: two paragraphs convey essentially the same information, including the same warning about wholesale replacement. The first sentence is front-loaded and clear, but the duplication makes it less concise than it should be.

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 adequately covers what the tool reads, why it should be used before updating, and how it can verify session tags. Since an output schema exists, the description need not detail return fields. It is contextually complete for a read operation, despite the redundancy.

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 both id and merchant_id having clear descriptions. The tool description does not add further parameter-specific details; it mentions update-related fields (content_md, tags_sub, tags_interview_set_filter) that are not parameters of this read operation. Baseline 3 applies because the schema handles parameter semantics well.

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 verb 'Read' and the resource 'one catalogue directory in full', enumerating settings, custom Markdown page, sub-directories, and matched sessions. This specificity distinguishes it from sibling tools like list_catalogue_directories 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?

The description explicitly says 'Read before updating' and explains that fields are replaced wholesale by the update tool, making the usage context clear. It also offers a verification use case. However, it does not name alternative tools or explicitly state 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses additional behaviors: returns compiled calc_definition_json, ordered questions in a round-trippable format, and that IDs should be preserved. It also notes row-level security, adding meaningful context 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 verbose and redundant: the 'same format' round-trip note appears in both paragraphs, and the second paragraph uses a different, inconsistent API name ('job-interview-create-from-array') not present in the sibling list. The front-loaded first paragraph helps, but the duplication and naming inconsistency harm 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?

The description covers the return contents (compiled calc_definition_json, ordered questions array, basic metadata), the round-trip use case, and row-level security. Since an output schema exists, it need not detail every field, but it provides enough context for an agent to understand behavior and select the tool 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?

The input schema already provides 100% coverage with a clear description of position_id as accepting either an interview definition or position definition. The tool description echoes this but adds no new parameter semantics beyond what the schema documents, so a 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 'Gets the definition/configuration of an interview (position)' and distinguishes from siblings like list_interviews by specifying it returns the ordered questions array and compiled calc_definition_json. The verb 'get/retrieves' plus explicit resource makes 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 provides explicit usage context: it mentions the round-trip workflow (read here, modify array, send to update_interview) and mentions access is subject to row-level security. It does not explicitly exclude alternatives, but the sibling list makes the choice clear.

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

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

Annotations already declare 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 declare readOnlyHint and idempotentHint, and the description adds behavior details: pagination with 1000 cap, merchant scoping, and the inclusion of legacy types. This is valuable context 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 two concise paragraphs, front-loading the key purpose and usage guidance. It avoids unnecessary repetition but could be slightly more structured (e.g., separating param details).

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 purpose, usage, behavioral nuances, and parameter intent. It mentions pagination limits and legacy types, making it complete for a list 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 descriptions for all 9 parameters. The description does not add per-parameter details but provides overall context (e.g., meaning of 'type' values). Since schema covers parameters, a 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 avatar/voice templates, explains how the 'type' field maps to interview modalities, and notes that the 'id' is used as interview_template_id in creation tools. This distinguishes it from sibling list tools and adds context beyond a simple 'list avatars'.

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 guidance on selecting templates by type for the desired experience, warns about legacy types that cannot be used, and mentions merchant scope and pagination. However, it does not explicitly compare to other list tools or state when to avoid 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 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 value beyond annotations by specifying authentication requirements and the return of one-time URLs, but does not detail side effects like email sending or error conditions. Annotations already indicate destructiveHint=true, so no contradiction.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value without fluff.

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

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

The description covers core functionality, authentication, and return value, and the schema covers all parameters. It is complete enough for an AI agent to understand usage, though it could mention edge cases like duplicate registration.

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 summarizes the purpose but does not add significant meaning beyond the schema's per-parameter 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 verb 'register' and the resource 'users/candidates for a specific interview', and specifies the outcome 'return their personal interview links'. It distinguishes from sibling tools like 'create_interview' or 'generate_interview_url'.

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 authentication (JWT vs service key) and mentions it can update existing profiles, but does not explicitly state when to use this tool vs alternatives or 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?

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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses key side-effects: partial updates keep unspecified values, null clears a nullable field, tags_sub replaces the whole list, and content_md null restores the default grid. This gives the agent a clear mental model of how the mutation behaves.

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 split into two redundant paragraphs, with the first summarizing and the second expanding slightly. While both are concise, the duplication of the core 'update a directory' concept and parameter list is unnecessary and could be tightened into a single paragraph 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 an 11-parameter mutation tool, the combined schema coverage (100%), annotations, output schema, and description provide sufficient context to understand the tool's behavior and parameters. The description highlights the most nuanced update paths, and the schema covers the rest, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters in detail. The description adds value by referencing the most complex parameters (tags_interview_set_filter, tags_sub, content_md) and their high-level effects, but does not add details beyond what the schema provides for the remaining 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's purpose using a specific verb ('Update') and resource ('coaching catalogue directory'), and enumerates distinct capabilities: rename, change session listing filter, re-order sub-directories, and author custom Markdown. This unambiguously distinguishes it from sibling create/get/list tools.

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

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

The description provides clear usage context by explaining partial-update semantics ('Only the fields present in the request body are written') and null-clears behavior. It does not explicitly name alternatives (e.g., 'use create_catalogue_directory for new directories'), but the action of updating an existing directory is well 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description details exact behaviors: partial updates, null clearing, diff-based question handling (unlink old, create new, never delete), no-op on resending unchanged array, and limitations on active interviews and language. This far exceeds the structured annotation information.

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 key points: 'Only the fields you send are changed' and 'welcome/thank-you messages are never changed' both appear twice. While front-loaded and structured, the redundancy makes it less concise than necessary. Still, it is organized and readable.

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 40 parameters and an output schema, the description covers all major behavioral traps: question diff semantics, null clearing, position vs interview field restrictions, active-interview limitations, and language immutability. It is complete enough for an agent to use the tool correctly without additional lookup.

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?

Even though schema coverage is 100%, the description adds significant meaning: it explains the diff algorithm for `questions`, the relationship between `status` and `interview_set_status`, that `recording` is not a full session recording, and which fields apply to single-stage vs multi-stage positions. This is essential context not captured 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 uses a specific verb ('Updates') and identifies the exact resource: 'the configuration of an existing interview (single-stage) or position (multi-stage).' It clearly distinguishes from siblings by focusing on updating existing entities, and explicitly notes what is not updated (e.g., welcome/thank-you messages, language), setting it apart from create/set-state 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?

Provides explicit guidance on when to use the tool vs alternatives: tells the user to read the interview first before changing questions, explains how to handle active interviews (set to draft for offline templates), and directs users to create a new interview to change language. It also warns that sending interview-only fields to a position results in a 422, clearly scoping valid usage.

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.