Repovive MCP Server

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

Annotations already indicate non-read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context by stating the caller must have edit rights and that access is granted based on email. It avoids contradicting the annotations and supplements them with an auth precondition.

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

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

Two short sentences with no filler. The core action and important prerequisite are front-loaded, and every clause earns its place.

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

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

For a simple 3-parameter tool with 100% schema coverage, an output schema, and annotations covering idempotency and destructive behavior, the description supplies the essential missing context: the permission prerequisite and the email-based targeting. Nothing critical is left unexplained 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 description coverage is 100%, so the baseline applies. The description reinforces the meaning of 'email' by saying access is granted by email address and aligns with the role examples ('edit or view'), but it does not add substantial new parameter-level detail beyond the schema.

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

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

Description states a specific verb ('grant'), resource ('access to a course'), and method ('by email address'). It also clarifies that both edit and view access can be granted, distinguishing this add operation from siblings like remove_course_editor and get_course_editors.

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 says when to use the tool: to grant edit or view access by email. It also provides a key prerequisite ('Requires edit rights on that course'). It does not explicitly name alternatives, but the context is clear enough for an agent to select it over related course-access tools.

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

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

The annotations already cover the read-only safety profile (readOnlyHint=true). The description adds useful context beyond that: the tool inspects the local host's toolchain and returns two categories of languages (actually runnable vs. merely known), which clarifies output semantics without contradicting 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?

Two sentences with no filler. The key qualifier ('actually run on this host (toolchain present)') is front-loaded, and the usage cue is given in the second sentence.

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 zero-argument, read-only tool with an output schema, the description covers what the tool reports and when to use it. Nothing needed to invoke it correctly is missing.

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

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

The tool has zero parameters, so the schema fully covers inputs; the baseline for no parameters is 4. No parameter explanation is needed, and the description appropriately focuses on output behavior instead.

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

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

States a specific verb ('List') and a precise resource ('languages the local judge can actually run on this host'), and clarifies the scope as 'alongside every language it knows about.' It clearly differentiates from repovive_judge_solution and other listing 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?

Explicitly instructs the agent when to invoke it: 'Check this before repovive_judge_solution.' This gives a direct decision rule and distinguishes it from the related judging 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 show this is a mutating, reversible, non-destructive operation. The description adds useful behavioral context by specifying the scope ('the authenticated account'), the recorded optional reason, and the fact that blocking is reversible with repovive_unblock_user. This goes beyond what the annotations provide 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?

Two sentences carry the essential information with no filler: the effect, the optional reason, and the reversal path. The most important scoping detail ('can no longer direct-message the authenticated account') appears immediately, making the description easy to scan.

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 two-parameter tool with a complete input schema, an output schema, and relevant annotations, the description is fully sufficient. It explains what the action does, who it affects, and how to undo it, so an agent has everything needed to select and invoke the 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 description coverage is 100%, and the schema already documents both user_id and reason clearly. The description restates the optional-reason idea but adds no new parameter-level meaning beyond what the schema provides, 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 states a specific action ('Block a user'), the exact target resource, and the precise effect: the blocked user can no longer direct-message the authenticated account. It also mentions the optional reason and explicitly names the reversal tool, distinguishing it from repovive_unblock_user and repovive_list_blocked_users.

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 indicates when to use this tool: when the goal is to stop a user from sending direct messages to the authenticated account. It also names the relevant alternative for undoing the action (repovive_unblock_user), though it does not explicitly list 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?

The description clearly explains the additive behavior: cases are added to existing content rather than replacing it. It also discloses the interactive-problem verdict behavior. Annotations already cover read-only/destructive hints, so the description adds meaningful behavioral context beyond 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?

Two sentences carry all essential information with no filler. The most critical behavioral caveat (append vs. replace) is front-loaded, and the interactive case is handled in a single follow-up clause.

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 simple two-parameter schema, full schema coverage, and presence of an output schema, the description covers everything needed to invoke the tool correctly. It explains the operation, the replacement alternative, and the interactive edge case.

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 input schema already fully documents both parameters. The description reinforces the interactive expectedOutput rule, but it does not significantly extend parameter understanding beyond what the schema already states.

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: "Append test cases to a draft in one call." It also explicitly distinguishes this from repovive_build_clear_testcases, which is the key sibling that could be confused with it.

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

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

The description gives clear usage guidance: use this to append, and use repovive_build_clear_testcases first if replacement is intended. It also includes an important conditional for interactive problems, telling the caller to omit expectedOutput.

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 signal readOnlyHint=false and idempotentHint=false, so the non-read-only nature is covered. The description adds meaningful behavioral context by stating that this action makes authored work visible on the platform and that explicit user approval is required — information not available from annotations alone.

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

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

Three sentences with no wasted words. The primary purpose is front-loaded in the first sentence, and the critical prerequisite and consent requirement follow efficiently 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 rich schema (100% parameter coverage), existing output schema, and annotations covering read-only/idempotent/destructive behavior, the description is complete for correct invocation. It adds the crucial preconditions and visibility consequence that are not encoded elsewhere.

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 parameters are fully documented in the schema. The description mentions 'draft' and 'contest' conceptually but does not add any detail about session_id or body_json beyond what the schema already provides; 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 states a specific verb and resource: 'Publish a draft by attaching it to a contest as a real problem,' which clearly identifies the operation and its role. However, it does not explicitly distinguish itself from adjacent sibling tools like build_push_problem or build_author_complete_problem, so the differentiation is implicit rather than explicit.

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

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

The description provides clear execution context: verify the draft builds cleanly first, and never call without explicit user approval. This tells the agent when it is appropriate to invoke the tool, though it does not name alternative tools or say 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 discloses substantial behavior: clearing test cases, writing multiple artifacts, returning a per-step report, and editing a private draft. However, it says it 'clears the existing test cases' while annotations declare destructiveHint=false, which is a direct contradiction. Per the rubric, this makes the score 1 despite otherwise strong disclosure.

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

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

The description is three sentences with no filler. It front-loads the core action, then gives the side effect, return semantics, and scope boundary. 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?

For a five-parameter tool with an output schema and rich annotations, the description covers destination, artifacts written, the reporting mechanism, and the draft-vs-contest scope. It is slightly less complete because the destructiveHint conflict leaves the safety profile ambiguous.

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 100% of the five parameters, so the baseline is 3. The description reinforces the replace_testcases behavior and references problem_json coming from repovive_generate_problem, but it does not add meaning beyond what the schema already documents.

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

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

The description names a specific verb and resource: 'Import a complete problem into a draft in one call', then enumerates exactly what gets written. It distinguishes this from the granular build_* sibling tools and from publishing by saying 'publishing it to a contest is a separate call'.

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

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

It clearly signals when to use this tool: when you want a complete, one-call import into a draft. It also sets an exclusion by noting publishing is separate. It does not explicitly name the alternative granular build_* tools for partial updates, so it stops short of full when/when-not guidance.

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

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

Annotations already cover idempotency and non-destructiveness, so the description only needs to add behavioral context. It adds that the run is 'currently executing' and associated with 'a draft,' but it does not explain what happens to partial build outputs or whether cancellation is asynchronous.

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 a single, front-loaded sentence with no filler. Every word contributes to the core meaning, and it is immediately scannable.

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 one-parameter cancellation tool with an output schema and idempotency annotations, the description is largely complete. The only minor gap is lack of explicit error behavior when no build run is currently executing, but that is implied by 'currently executing.'

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add additional meaning about session_id, such as how to obtain it or what kind of session it refers to, but it does not need to because the schema already documents it.

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

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

The description uses a specific verb ('Cancel'), a clear resource ('build run'), and a scoping condition ('currently executing for a draft'). This distinguishes it from related tools like repovive_build_run_status without needing to inspect the schema.

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

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

The description implies the tool is for stopping an in-progress build run, but it does not explicitly state when to prefer it over alternatives or mention any preconditions like needing a valid session id. Usage context is present but not elaborated.

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 supply readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds valuable context beyond these: the deletion is irreversible ('This cannot be undone') and is limited to 'manually added' cases, implying generated cases are untouched. This clarifies the operational impact without contradicting 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 sentences with zero redundancy. The action and scope are front-loaded, followed immediately by the critical caution ('cannot be undone') and a usage hint. Every word 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?

For a one-parameter destructive action with a rich annotation set and an output schema, the description covers the essential information: what is deleted, scope ('manually added'), irreversibility, and when to call it. Nothing necessary for correct invocation is missing.

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

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

Schema description coverage is 100%: the only parameter, session_id, is documented with type, minLength, and 'Build session id'. The description adds no parameter-level detail, and the schema already provides sufficient semantic grounding, so the baseline of 3 applies.

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

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

Description states a precise verb ('Delete'), a specific resource ('test case'), and the scope ('every manually added test case from a draft'). It clearly distinguishes itself from sibling repovive_build_delete_testcase (which deletes a single test case) and repovive_build_add_testcases (which adds them).

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 actionable guidance: 'use it before uploading a replacement set' signals the intended workflow. It implies bulk removal vs. per-testcase deletion among siblings, though it does not explicitly name the alternative (repovive_build_delete_testcase) or state 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 provide only idempotent and destructive hints, so the description carries the behavioral burden. It adds substantial detail: schema validation, reference-solution judging, known-wrong-solution negative check, per-problem verification report, and the required success condition. This is exactly the kind of workflow transparency an agent needs.

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 dense sentences: the first states purpose and verification steps, the second states return shape and the required postcondition. Every sentence earns its place with no filler or duplication of schema content.

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

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

For a complex 5-parameter tool, the description covers the full workflow, return format, and success criterion, and the output schema covers return details. It is slightly incomplete about the behavior when verify=false and does not explicitly state whether the contest is persisted or only returned, though 'import-ready' implies the latter.

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

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

Schema description coverage is 100%, and the schema already documents each parameter including title, problem_kinds ordering, seed derivation, verify behavior, and hidden test count. The description reinforces the problem_kinds and verification concepts but adds no new per-parameter meaning 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 uses a specific action—'Generate a whole contest... and verify it'—and details the verification workflow (schema-check, judge reference solution, confirm known-wrong solution fails). This clearly differentiates it from single-problem or validation siblings like generate_problem, validate_problem, and judge_solution.

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: this is the orchestration tool for producing a complete contest from an ordered list of generator kinds, and it includes an actionable guardrail ('require verification.all_passed before using it'). It does not explicitly name alternatives or state when not to use it, but the intended use case is unambiguous.

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 beyond the annotations by explaining the draft's privacy state and the difference between creating and resuming. This is valuable behavioral context for a mutation tool. 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 sentences, front-loaded with the core action, and contains no filler. Every sentence contributes to understanding the tool's behavior.

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

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

For a simple 3-parameter tool with a full schema and output schema, the description covers purpose, key behavioral nuance, and privacy. It could mention how to discover existing drafts, but the schema and annotations largely fill gaps.

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 meaningful semantic guidance for force_new beyond the schema, specifically that setting it false resumes a same-named draft. This elevates the score slightly.

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 starts with a specific verb and resource: 'Start a new problem draft on Reprovive and return its session id.' This clearly identifies the tool's purpose and distinguishes it from sibling tools like list or delete session 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?

It provides practical guidance by explaining that setting force_new=False resumes an existing draft rather than creating another. It also notes privacy semantics. It does not explicitly name alternative tools, but the guidance is clear enough for most 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?

Beyond the annotations (destructiveHint=true), the description explicitly warns that gen-data lines invoking the generator will stop working and that the gen-data script must be updated accordingly. This is valuable behavioral disclosure that prepares the agent for the tool's ripple effects. 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 two sentences, front-loaded with the primary action and scoped context, followed immediately by the key side effect and required follow-up. No filler or redundant wording.

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 two-parameter delete operation with an output schema, the description fully covers what the agent needs to know: the target, the scope, and the consequential gen-data impact. 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 input schema already sufficiently documents session_id and generator_name. The description does not add extra parameter-level context, but given the complete schema coverage, a baseline score 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 states a specific verb ('Remove'), a precise resource ('a named generator'), and context ('from a draft'). This clearly distinguishes it from related build tools like repovive_build_set_generator or repovive_build_delete_session. The action is unambiguous even without comparing to sibling schemas.

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

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

The description implies when to use this tool: when a generator should no longer exist in a draft, and it adds a follow-up instruction to update the gen-data script. However, it does not name alternatives or state when not to use it, leaving the 'when vs. when-not' guidance largely implicit.

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 beyond the annotations by specifying exactly what gets destroyed (statement, test cases, solutions, generators) and emphasizing irreversibility. This aligns with destructiveHint=true and readOnlyHint=false, and adds concrete behavioral context an agent needs before calling.

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 with no filler. The core destructive behavior and contents are stated first, and the user-confirmation requirement is added immediately after. Every clause earns its place.

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

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

For a single-parameter destructive tool with a complete input schema and an output schema available, the description covers all essential context: what is deleted, the scope of deletion, irreversibility, and the need for user confirmation. 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?

The input schema already fully documents the single parameter 'session_id' with the description 'Build session id to delete.' The tool description adds no additional meaning beyond the schema, 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 states a specific action ('Permanently delete') on a specific resource ('a problem draft') and enumerates what it contains. This clearly differentiates it from sibling delete tools that target narrower pieces like generators or testcases.

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

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

The description gives explicit usage guidance: 'confirm with the user before calling.' It does not explicitly enumerate alternatives or when-not-to-use cases, but the destructive, irreversible nature is clearly flagged, which is the key conditional for invoking 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 mark the tool as destructive, but the description goes further by stating 'This cannot be undone,' which is crucial behavioral context for an agent deciding whether to invoke it. It also clarifies that the operation acts within a draft, adding scope beyond what annotations alone convey.

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

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

Two compact sentences deliver the action, the resource scope, the ID source, and the irreversibility warning. Every sentence earns its place with no filler or 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?

For a simple two-parameter delete operation with destructive annotations and an output schema, the description covers all essential context: what to delete, where the ID comes from, and that deletion is permanent. Nothing needed for correct invocation is missing.

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

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

The schema already covers both parameters fully, so baseline is 3. The description adds value by directly telling the agent to source testcase_id from repovive_build_list_testcases and 'by its id,' reinforcing the link between the parameter and the list operation, which slightly exceeds bare 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 a specific action (delete) on a specific resource (one test case from a draft) and by a specific identifier (its id). It also references repovive_build_list_testcases, which distinguishes it from related test-case operations like clear_testcases or add_testcases.

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 instructs the agent where to obtain testcase IDs, providing a clear prerequisite for use. It does not explicitly contrast with alternatives such as clearing all test cases, but the target use case—deleting a single test case from a draft—is clear enough for 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 convey readOnlyHint and openWorldHint, so the safety profile is covered. The description adds behavioral context by revealing what the returned data contains: the main test solution, alternatives, and their expected verdicts, which helps the agent anticipate the result without contradicting 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 a single front-loaded sentence that immediately states the action and resource, then adds the meaningful distinction about main versus alternative solutions. There is no filler or redundant restatement of the title.

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

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

For a read-only fetch tool with one documented parameter and an output schema present, the description provides sufficient context: what the solutions are, what they contain, and the expected verdicts. No critical operational detail appears 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 only parameter, session_id, is already fully described in the schema as 'Build session id' with 100% schema description coverage. The description adds no further parameter-specific detail, but it does connect the session concept to the draft context, matching the schema baseline of 3.

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

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

The description names a specific verb ('Fetch') and resource ('solutions attached to a draft'), and distinguishes the content from related tooling by specifying 'the main test solution plus any alternatives with their expected verdicts.' This makes the tool's role clear without needing to inspect the schema or siblings.

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

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

The description clearly situates the tool within the draft-building workflow by stating it reads solutions attached to a draft. It does not explicitly name alternatives or exclude other operations, so it stops short of full when-to-use-versus-not guidance.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds meaningful context: it enforces schema, house-style checks, judges against tests, and requires verification.all_passed before publishing. This goes beyond annotations and clarifies the safety gate for publishing.

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 that front-load the primary purpose and include essential constraints (slots, points, difficulty, verification). No unnecessary detail.

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

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

The description covers the core behavior: building a full round, generator mapping, scoring, difficulty, and the verification requirement before publishing. With an output schema present, the description is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds context about slots A-G and difficulty curve, but does not elaborate on the parameters themselves beyond what the schema already provides, 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 a specific verb (build) and resource (a full Repovive-format round), and specifies house-style generators per slot A-G, making it distinct from sibling tools like generate_house_problem or build_contest.

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 does not explicitly state when to use this tool over alternatives, nor does it mention excluded cases. Its purpose is clear but selection guidance is left implicit, meriting a 3.

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 annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the useful context that the list is scoped to attachment eligibility for the authenticated account, but it does not disclose additional behavioral details such as ordering, pagination, or whether the list is a snapshot.

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 sentences with no filler. The first sentence front-loads purpose and scope, and the second provides an actionable next step.

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 parameterless read-only list, the description covers what the tool returns and how to use the result. Combined with the readOnly/openWorld annotations and the output schema, an agent has enough information to select and invoke the 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?

The tool has zero parameters, so there is no parameter documentation burden. The description adds value by telling the agent that the result contains contest ids and how those ids should be used.

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: it lists contests the authenticated account may attach a finished draft to. It also explicitly names the downstream tool, repovive_build_add_to_contest, which distinguishes it from generic contest-listing tools like repovive_list_contests.

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 states when to use this tool: to discover contests that a finished draft can be attached to. It gives an actionable follow-up instruction to feed one of the returned ids to repovive_build_add_to_contest, though it does not explicitly list exclusions or alternative tools.

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

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

Annotations already establish readOnlyHint and openWorldHint. The description adds value beyond those by defining the session scope ('owned by the authenticated account') and the returned fields ('session ids and current state'), which helps the agent anticipate what it will receive.

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 deliver the core action, scope, returned information, and the important prerequisite relationship to other build tools. No filler or redundant restatement of the title.

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

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

This is a parameterless read-only list operation with an output schema available, so the description only needs to state scope and purpose—which it does completely. The note that other build tools depend on these ids is useful additional 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?

The input schema has zero parameters, so there is no parameter burden for the description to carry. The mention of 'session ids' clarifies meaningful output concepts but no parameter detail is needed here.

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

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

The description names a specific verb ('List') and resource ('problem-draft build sessions owned by the authenticated account'), and specifies the returned content ('session ids and current state'). It clearly distinguishes this list operation from the many create/update/delete build-session siblings.

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

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

The phrase 'Every other build tool needs one of these ids' gives clear contextual guidance to call this before other build tools. It does not explicitly name a specific alternative or state when not to use it, but the prerequisite framing is strong.

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?

readOnlyHint and openWorldHint annotations already establish this as a safe read operation; the description adds that the list reflects the current draft contents and includes the ids used by the deletion tool. No behavior such as pagination or errors is described, but for this simple read-only list the annotation coverage is sufficient.

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

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

A single sentence that front-loads the action and resource, then adds the only extra detail an agent needs (id linkage to deletion). No filler or repetition.

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 one required parameter, an output schema present, and read-only annotations, the description supplies enough context to invoke correctly. It ties the result to a related deletion command, and no important behavioral or return-value detail is missing.

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

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

Schema coverage is 100% with a clear description for session_id, so the description does not need to add parameter detail. It adds no semantics beyond the schema, which meets the baseline.

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

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

The description names the exact operation ('List') and resource ('test cases currently stored in a draft'), and explicitly mentions the per-case ids needed by repovive_build_delete_testcase, which distinguishes it from sibling tools like add/clear/delete testcases.

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 clear context that this is for inspecting a draft's test cases and connects the output to repovive_build_delete_testcase by providing the needed ids. It does not explicitly state when not to use it or name alternatives, so it stops short of a full 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 readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds meaningful behavioral detail by explaining that the tool triggers generators, validation, and test runs asynchronously, and that the caller must poll for results. 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 two concise sentences: the first states the core action and pipeline steps, the second gives the required follow-up. Every sentence carries useful information with no filler.

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

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

For a single-parameter async pipeline starter with a full output schema and annotations, the description covers the main workflow and the necessary polling step. It could mention prerequisites or failure behavior, but nothing essential to invoking the tool correctly is missing.

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

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

Schema description coverage is 100%, and the only parameter, session_id, is already described as 'Build session id'. The description refers to a draft session but does not add new parameter-level meaning beyond the schema, so the baseline score 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 a specific action ('Kick off Repovive's build pipeline for a draft') and enumerates what the pipeline does: run generators, validate inputs, and run solutions against tests. This distinguishes it from related build tools like repovive_build_run_status, which is explicitly named only as a follow-up.

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 use ('for a draft') and explicitly instructs the agent to poll repovive_build_run_status for the outcome. It does not enumerate exclusion cases or alternative tools, but the usage context is clear enough for 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?

The description says test cases are appended to whatever the draft already holds, implying repeated identical calls would keep adding test cases and thus change state. This contradicts the idempotentHint=true annotation, which states the operation is idempotent. No other behavioral context is added beyond that, and the contradiction is severe.

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 only two sentences long, front-loads the core purpose, and uses the second sentence to point to the alternative. Every sentence earns its place, with no redundant filler.

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

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

The description gives the main behavior and a clear pointer to the alternative, and the output schema exists to clarify returns. However, the idempotency contradiction is unresolved, and the description does not clarify whether metadata and statement are overwritten or merged when writing into an existing draft, leaving an important usage gap.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds only minimal context by noting problem_json contains metadata, statement, and optionally test cases, which mostly overlaps with the schema description and does not significantly deepen parameter 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 action 'Write a problem object into an existing draft' and enumerates the components: metadata, statement, and optionally test cases. It also differentiates itself from the sibling tool repovive_build_author_complete_problem by naming what that tool does instead.

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 explains when to use this tool versus the alternative: it appends test cases, and for a complete import that clears old cases and uploads reference solution, editorial, and validator, the agent should use repovive_build_author_complete_problem. This gives clear when/when-not guidance.

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

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

With readOnlyHint=true and openWorldHint=true, the annotations already signal a safe read operation. The description adds behavioral context by indicating the response includes progress, per-stage results, and errors, which goes beyond the annotation alone. It does not deeply discuss lifecycle or polling details, but that is not a major gap for a simple status check.

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 a single, well-structured sentence that front-loads the main action and includes only relevant details. There is no redundancy or filler.

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

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

The tool has one required parameter, an output schema is present, and annotations cover the read-only nature. The description explains what the tool does and references the preceding operation, making it complete for an agent to invoke 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?

The schema fully documents the single `session_id` parameter with a description ('Build session id'), so schema coverage is 100%. The tool description adds no additional semantic detail about the parameter, but none is needed given the schema already covers it.

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

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

The description clearly states the action ('Check the status of a draft's build run') and identifies the specific resource ('started by repovive_build_prepare_judge_target'). It also lists the kind of information returned (progress, per-stage results, errors), which distinguishes it from sibling tools like repovive_build_cancel_run.

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 stating the tool is for checking a build run started by repovive_build_prepare_judge_target. It does not explicitly enumerate alternatives or when-not-to-use scenarios, but the context is specific enough for an agent to infer the intended workflow.

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 a mutating, non-destructive, idempotent operation. The description adds meaningful behavioral context beyond annotations by explaining that the checker 'replacing exact output matching', which tells the agent what side effect to expect. No contradiction with annotations exists.

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

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

Two sentences deliver the action, the behavioral change, and the usage condition with no filler. The key behavior ('replacing exact output matching') is front-loaded before the use-case guidance, making it easy for an agent to parse quickly.

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 two-parameter mutation tool with high schema coverage, annotations, and an output schema, the description is nearly complete: it states what the tool does and when to use it. It does not mention prerequisites such as an existing session or how the checker source should be formatted, but these are minor gaps given the output schema and parameter descriptions.

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 parameters session_id and checker_source are already documented in the schema. The description names the checker but does not add extra semantic detail like language, format, or constraints beyond what the schema provides, 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 uses a specific verb ('Attach') and resource ('custom checker to a draft'), and it clearly distinguishes the tool's role by stating it replaces exact output matching, which sets it apart from sibling build tools like set_validator or set_solutions. The purpose is immediately understandable without needing the schema.

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

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

The description gives explicit when-to-use guidance: 'Use it when a problem accepts multiple correct answers or needs tolerance-based comparison.' It does not discuss when not to use it or name alternatives, but the usage condition is clear and actionable.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the dependency that generators must be defined before this script, but does not describe overwrite behavior or other side effects beyond what annotations imply.

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 with no filler. The first sentence states the action and format; the second names the prerequisite tool. Information is front-loaded and each 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?

For a simple two-parameter tool with rich annotations and an output schema, the description is complete: it states what the tool does, the exact content format, and the required prerequisite. Nothing essential is missing.

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

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

Schema coverage is 100%, but the description adds meaningful semantics: gen_data_content must contain one generator invocation per line and each line produces a hidden test file. It also clarifies that session_id refers to a draft, linking it to the build session context.

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, 'Set,' and identifies the resource as 'a draft's gen-data script.' It clearly distinguishes this from sibling tools like repovive_build_set_generator by defining the script format: one generator invocation per line, each producing one hidden test file.

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 ordering guidance: define generators first using repovive_build_set_generator. This helps the agent understand the prerequisite and differentiates this tool from the generator-setting sibling, though it does not explicitly state when not to use the 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=false, idempotentHint=true, and destructiveHint=false, covering the write and non-destructive nature. The description adds that the generator is stored 'in a draft' and its role in the workflow, which provides some context but does not significantly expand 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 sentences with no fluff. The first sentence states the core action, and the second connects it to the broader workflow. Information is front-loaded and each 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 simple parameters, comprehensive schema, annotations covering safety/idempotency, and an output schema present, the description fully equips the agent. It explains the tool's role in the test-generation pipeline, making it complete for correct invocation.

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

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

The input schema has 100% coverage with clear descriptions for all three parameters, so the description need not add parameter details. It does imply the generator_name is a unique identifier via 'named', but this adds marginal value on top of 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 verb 'store' with a specific resource ('a named test generator program in a draft'). It is differentiated from related siblings like repovive_build_delete_generator and repovive_build_set_gen_data by explaining that generators are stored for later invocation by the gen-data script.

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 explains the purpose of the stored generator (invoked from repovive_build_set_gen_data), giving clear context for when this tool is relevant. It does not explicitly state when not to use it or name alternatives beyond the implicit connection to the delete generator tool, but the context is sufficient.

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, the description reveals that the tool sets the draft's editorial pages, expects a JSON list of title/content objects, and that '[]' clears the pages. It doesn't mention that 'null' also clears, but the schema covers that, and annotations already convey idempotency and non-destructiveness.

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 with no filler. The core action is front-loaded, and the input format and clearing behavior are stated immediately and efficiently.

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 two-parameter setter with an output schema and matching annotations, the description provides everything an agent needs: what the tool does, what input to pass, and how to clear pages. Omitted details like the null clearing option and response shape are already in the schema/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?

Schema description coverage is 100%, and the description mostly restates what the schema already says about pages_json ('JSON list of {"title", "content"}' and '[]' to clear). The description adds little beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('Set'), a clear object ('a draft's editorial pages'), and explains what those pages are ('post-contest explanation shown with the problem'). This distinguishes it from the many build_* sibling tools that update statements, generators, or testcases.

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 operational context—it targets a draft's editorial/learn pages and shows the expected input and clearing behavior. It doesn't explicitly name alternatives or exclusions, but the operation is unique enough among siblings that no alternative is needed.

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

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

There is an annotation contradiction: destructiveHint is false, yet the description says replace=False keeps existing alternatives, implying that the default replace=True replaces or overwrites existing solutions. This is destructive behavior and conflicts with the annotation, which could mislead an agent into thinking the tool is safe to run without preserving existing 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?

Two dense sentences, no filler. The primary behavior is front-loaded, and the replace=False guidance is integrated naturally without bloating the description.

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 rich schema coverage, an output schema, and a description that explains the core behavior and parameter intent. The main missing piece is an explicit statement that the default behavior replaces existing solutions, rather than relying on inference from 'Set replace=False to keep the existing alternatives'.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the intended meaning of expected_verdict with examples (AC, WA, TLE) and by framing replace=False as a way to append deliberately wrong or slow solutions. It does not repeat the schema verbatim.

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

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

The description clearly states a specific action: attaching a solution to a draft with an expected verdict and optionally making it the main test solution. It distinguishes itself from read-style siblings like repovive_build_get_solutions by focusing on the setting/attaching 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 provides a concrete use case: setting replace=False when adding deliberately wrong or slow solutions that test data must reject. It does not explicitly name alternatives or state when not to use the tool, so it falls short of a 5, but the guidance is clear and actionable.

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?

It explains what the attached validator does (reads generated tests, asserts constraints, blocks malformed data from going live) and that this is a pre-publication, non-destructive build step. The annotations already convey idempotency and non-destructiveness, and the description adds workflow context 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?

Two short sentences with no filler: the first names the action and target, the second explains the validator's purpose and timing. Every sentence earns its place and the key action is front-loaded.

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

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

For a simple two-parameter, non-destructive, idempotent setter with a full schema and output schema, the description covers the essential use case. It could be slightly more explicit that 'draft' corresponds to the session_id parameter, but sibling tool names and the schema make that connection recoverable.

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 functional meaning to validator_source by stating that it reads generated tests and asserts constraints, and it clarifies that session_id refers to the draft/build context. This is more than the schema labels provide.

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

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

The description names a specific verb ('Attach') and a distinct resource ('input validator to a draft'), making the action unambiguous. This clearly separates it from sibling set_* tools like set_generator or set_custom_checker, whose resources are different artifacts.

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: the validator is attached during draft preparation and is meant to catch malformed test data before publication. It does not explicitly state when not to use this tool or name alternatives, so it stops short of full routing guidance.

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

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

The annotations already mark mutation, idempotency, and non-destructive behavior, so the description adds the crucial partial-update trait: only the arguments passed are changed, and the rest keep their current values. This is a meaningful behavioral detail beyond what the annotations provide.

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-load the operation and scope, then state the partial-update behavior. There is no filler, redundancy, or restatement of field types already in the schema.

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 is simple, has full parameter documentation, and has an output schema, so the description does not need to explain return values. It could have stated null-clearing behavior or draft/session prerequisites, but for a metadata PATCH the essential calling logic is complete.

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

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

Schema description coverage is 100%, so the schema already documents slug, difficulty, time_limit, memory_limit, and is_interactive individually. The description groups them as metadata and clarifies partial application, but it does not add per-parameter meaning 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?

Explicit verb 'Update', specific resource 'draft's metadata', enumerates the five fields, and indicates it operates on a build session. This clearly distinguishes it from siblings like repovive_build_update_statement and repovive_build_update_sources by identifying metadata as the target.

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 makes the intended use clear—updating metadata on a build draft—and the partial-update semantics indicate this is the tool for targeted field edits. It does not explicitly name alternatives or exclusion conditions, but within the build_* sibling cluster the scope is evident.

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=false, idempotent=true, destructive=false; the description adds context about it being a raw fallback. However, it does not surface that the raw body can include deleteGeneratorName, which is a destructive operation despite destructiveHint=false, so the safety picture remains incomplete.

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 with no filler; the action and the key routing guidance are front-loaded. Every word contributes to selection and safe invocation.

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, a fully-described body_json parameter, and explicit alternatives, the agent has enough to decide when to use this tool and how to call it. The sibling context is large, but the description narrows the decision effectively.

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 heavy lifting is done by the body_json and session_id descriptions. The tool description adds no parameter-level detail but does not need to; baseline 3 applies.

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

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

The description uses a specific verb ('Send') and resource ('raw update-sources body to a draft') and immediately frames it as the fallback for fields typed tools do not cover. This clearly separates it from the many sibling build 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?

It explicitly says to prefer repovive_build_update_statement, _set_generator, _set_gen_data, _set_validator or _set_custom_checker unless something they omit is needed. This gives the agent a concrete routing rule 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?

Annotations already convey readOnlyHint=false, destructiveHint=false, idempotentHint=true, so the description doesn't need to repeat those. It adds valuable behavioral detail: the partial-update semantics ('Only the arguments you pass are changed') and the validation quirk about inline math followed by a period. This goes beyond what annotations and schema provide.

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

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

The description is two sentences with no filler. It front-loads the tool's purpose and the key behavior (partial updates), then adds a specific formatting rule. Every clause earns its place.

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

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

Given an output schema exists (the return value is presumably documented there), the description does not need to explain output. It covers the core function, the partial-update behavior, and a critical formatting restriction. It doesn't mention that a session must already exist, but that is implied by the required session_id parameter and the 'draft' phrasing. The tool is sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, with each parameter (tags, title, constraints, description, etc.) having a short description. The tool description adds only a generic 'markdown with LaTeX' note, which partially overlaps with the schema's description field. There is no elaboration on syntax or constraints beyond what the schema already documents, so it meets the baseline but does not add significant extra semantic value.

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

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

The description clearly states the tool writes the statement of a draft, naming all the components (title, description, input/output formats, constraints, interaction protocol, tags) and the format (markdown/LaTeX). This distinguishes it from sibling tools that update other aspects of a problem (like sources or testcases), even though it doesn't explicitly name an alternative.

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 partial usage guidance: 'Only the arguments you pass are changed' implies partial updates, and the warning about LaTeX formatting is a practical constraint. However, it does not explicitly say when to use this tool versus other update tools (e.g., repovive_build_update_problem_info) or mention any exclusions or prerequisites beyond requiring a session_id.

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 annotations already declare readOnlyHint and openWorldHint, and the description adds the key behavioral fact that the call is unauthenticated and purely a health/diagnostic check. This is appropriate context beyond what annotations provide, with 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?

Two sentences with no filler. The core action is front-loaded, and the second sentence adds the one meaningful usage detail an agent needs: this is for reachability checks.

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 zero-parameter diagnostic getter with an output schema, the description fully covers purpose, usage context, authentication expectations, and behavioral characteristics. Nothing necessary for correct invocation is missing.

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

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

The tool has zero parameters and the schema coverage is effectively complete. The description does not need to explain parameters; the baseline of 4 applies since there is nothing missing for an agent to call it correctly.

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 ('Return') and names the exact resource ('deployed Repovive web-app build version'). It also characterizes the call as an unauthenticated health/diagnostic operation, clearly distinguishing it from sibling tools like repovive_build_run_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?

It explicitly tells the agent when to use it: to check that the platform is reachable. It provides clear context but does not discuss when not to use it or name alternatives, though no real alternative exists among siblings for this health check.

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 fully aligns with the readOnlyHint=true annotation – it is a check operation that lists deviations, implying no side effects. It adds behavioral detail beyond annotations by specifying the exact checks performed (memory, time limits, tags, sample explanation) and the output as a list of deviations. No contradiction exists, and the description enriches the agent's understanding of the read-only nature.

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 a single, well-structured sentence. It front-loads the primary action ('Check a problem against Repovive's measured house style') and then efficiently lists the specific criteria in a compact, comma-separated enumeration. There is no redundant wording or filler, making it both concise and clear.

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 is simple with one parameter, a clear output schema (exists), and a description that fully enumerates the checks performed. The description covers all relevant behavioral aspects for an agent to call the tool correctly. It does not explicitly discuss error handling or input validation beyond the schema's minLength, but given the simplicity and output schema coverage, these are minor gaps. Overall, the description is complete enough 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?

The schema description coverage is 100%, as the single parameter 'problem_json' is described as 'A problem object as a JSON string' with a minLength of 2. The tool description adds no additional meaning to this parameter beyond stating it is a problem; it does not explain expected structure, formatting nuances, or how the JSON string maps to the checks. Since schema already covers the parameter, the description does not contribute extra value, 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 verb 'Check' and resource 'problem against Repovive's measured house style' and enumerates the specific deviations it checks (input/output braced-array notation, t bound, tags, memory, time limit, points value, sample). This makes the tool's purpose unambiguous and distinguishes it from sibling validators like repovive_validate_problem, which would cover general problem validation.

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 for when to use this tool: when checking whether a problem conforms to the house style. It lists the exact aspects checked, which helps an agent decide relevance. However, it does not explicitly name alternatives or state when to use a different validator (e.g., repovive_validate_problem), so it lacks explicit exclusions or alternative guidance.

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

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

The readOnlyHint and openWorldHint annotations already establish that this is a read-only, externally changing check. The description adds 'currently' and 'available for booking,' reinforcing the volatile, pre-booking nature of the answer, but it provides no further behavioral detail such as effect on capacity or confirmation semantics. 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?

A single sentence that front-loads the verb and resource, with no filler or repetition of the tool name. Every word contributes to the meaning.

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 zero-parameter read-only check with an output schema and safety annotations already present, the description needs only to state what is being checked and why. 'Report whether Repovive currently has mock-interview capacity available for booking' does that completely.

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 zero properties, so there are no parameter semantics for the description to explain. Baseline for zero-parameter tools is 4; no additional parameter guidance is needed.

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 uses a specific verb ('Report') and resource ('mock-interview capacity') and clarifies the exact question being answered ('whether ... available for booking'). This distinguishes it from interview-related siblings such as repovive_get_interview_prices and repovive_list_interview_sessions, which address price and session listing rather than availability.

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 phrase 'currently has ... available for booking' gives a clear context: this check is the precondition for attempting a booking. It does not, however, name alternative tools or give when-not-to-use guidance, so it falls short of an explicit routing statement.

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, so the safety profile is known. The description adds meaningful behavioral context by specifying that it returns both eligibility and remaining quota, scoped to the authenticated account. This goes beyond simply restating the tool name or title, though it still leaves exact output field details to the output 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?

A single, information-dense sentence that immediately states the purpose and scope. No filler or redundant wording is present.

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 zero-parameter, read-only eligibility check with an output schema present, the description fully covers what an agent needs to know to invoke it correctly. It identifies the subject (authenticated account) and the two key outputs (eligibility and remaining quota).

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 tool has zero parameters, so there is nothing for the description to document. Baseline 4 is appropriate; no parameter ambiguity exists.

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 precise verb ('Report whether') and clearly specifies the resource: the authenticated account's ability to issue contest invitations and remaining quota. This distinguishes it from sibling tools like get_contest_invite_link, which generates a link, and check_interview_capacity, which concerns 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 this is a pre-flight check before inviting users to contests, but it does not explicitly state when to use it versus alternatives or when not to use it. There is no mention of exclusion conditions or related tools.

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

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

Annotations already indicate readOnlyHint=false and idempotentHint=false. The description adds important behavioral context: this is a real paid transaction that returns a payment URL and should only be invoked after user confirmation, which is beyond what the annotations alone convey.

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

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

Two compact sentences deliver the core purpose, the critical side-effect warning, and a mandatory user-confirmation instruction. Every word earns its place, and the main behavioral caution is front-loaded.

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

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

With one simple parameter, an output schema, and annotations covering safety traits, the description is sufficient. It names the authenticated account context, the payment nature, the return value, and the required user confirmation—nothing essential is missing.

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

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

Schema coverage is 100% and the sole parameter, vive_amount, is adequately described as 'Amount of Vive to purchase.' The description adds useful context about the purchase flow but does not add new meaning to the parameter itself, so the baseline of 3 applies.

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

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

The description uses a specific verb-resource pair ('Start a paid checkout to buy Vive points') and states the key output ('return the payment URL'). It is clearly distinct from sibling tools, none of which handle Vive checkout.

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 strong situational guidance by warning that this 'begins a real purchase flow' and instructing the agent to 'always confirm the amount with the user before calling.' It does not explicitly name alternatives, but the context makes the appropriate usage 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 destructiveHint=true and readOnlyHint=false, but the description adds important behavioral detail: deletion is permanent, cascades to 'everything attached to it,' and requires admin rights. This goes beyond the structured hints and appropriately warns an agent about the consequence.

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, front-loads the destructive scope, and includes the critical user-confirmation warning without unnecessary detail. 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?

For a simple admin-delete operation with one well-documented parameter and an output schema, the description fully covers the necessary context: what it does, what is required, and what the agent must do before invoking it.

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 only parameter, contest_id, is already documented in the input schema. The description adds no further parameter-specific semantics, but none are needed given the single, clearly-described identifier.

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 names a specific verb and resource: 'Permanently delete a contest and everything attached to it.' It unambiguously distinguishes itself from update_contest, get_contest, and other contest-related 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 gives clear usage context: the caller must have contest administration rights and must confirm with the user before calling. It does not explicitly name alternatives or exclusion conditions, but for an irreversible admin delete, the prerequisites and warning are the most relevant guidance.

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

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

Annotations already mark the operation destructive, but the description adds important behavioral context: 'This cannot be undone' and that the conversation history is deleted. The confirmation requirement is extra safety guidance beyond what annotations provide.

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 with no filler. The first sentence states the action, scope, and target; the second delivers the critical irreversibility warning. Both sentences earn their place and are front-loaded.

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

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

For a single-parameter deletion tool with an output schema and destructive annotations, the description covers the essential facts: what is deleted, for whom, and the irreversible nature. No additional behavioral details are needed to call it correctly.

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

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

There is only one parameter, conversation_id, and the schema describes it with 100% coverage. The description's phrase 'direct-message conversation' adds minor context but does not materially enhance the schema's 'Conversation id' description, so it stays at the baseline for high schema coverage.

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

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

States a specific verb and resource: 'Delete a direct-message conversation and its history for the authenticated account.' The phrase 'direct-message conversation and its history' distinguishes it from the sibling delete_direct_message and other delete tools, so an agent can identify the correct target.

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

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

The description implies the tool should be called when the user wants to remove an entire DM conversation, and it adds a clear precondition: 'confirm with the user before calling.' However, it does not explicitly contrast this with alternatives like delete_direct_message or mention cases where this tool should not be used.

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 state destructiveHint=true and readOnlyHint=false. The description goes beyond this by emphasizing irreversibility ('This cannot be undone') and requiring user confirmation, which is meaningful added context. It also narrows the operation to messages the authenticated account sent.

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

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

Two short sentences convey the action, the restriction, the irreversibility, and the required user confirmation without any wasted words. The most important caveat is front-loaded.

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

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

For a simple one-parameter tool with a full input schema, an output schema, and annotations covering destructiveness, the description provides all needed operational context: what is deleted, who can delete it, and what to do before invoking.

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 covers the single parameter with 100% description coverage, so the description need not add much. It does reinforce that the message must be a directly sent message, but it adds no additional details about message_id 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 uses a specific verb ('Delete') and a precise resource ('a single direct message the authenticated account sent'), clearly distinguishing it from deleting an entire conversation or sending a message. The scope is 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 clearly indicates this is for single direct messages and only for messages sent by the authenticated account, which is essential context. It also instructs the agent to confirm with the user before calling, but it does not explicitly name sibling alternatives like repovive_delete_conversation.

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 the description complements this by explaining the diff output categories and the 'same entity' constraint. It does not describe error cases or edge behavior, but for a read-only diff with an output schema, the added behavioral context is sufficient.

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 with no wasted words. The first sentence states the core action and output; the second provides the practical use case. It is appropriately sized and front-loaded.

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

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

For a read-only diff tool with three fully documented parameters and an output schema, this definition is complete. It covers what the tool does, what output to expect, the same-entity constraint, and the recommended use case, with annotations covering the safety profile.

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 from_revision_id and to_revision_id clearly labeled as older and newer, and response_format documented with its enum. The description adds no parameter-level detail beyond the schema, but it does not need to because the schema fully covers the parameters.

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

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

The description states a specific verb and resource: 'Compare two saved revisions of the same entity' and specifies the output as 'added, removed and modified' field-level changes. This clearly distinguishes it from related sibling tools like get_revision or restore_revision, especially with the rollback framing.

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

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

The description gives explicit usage context: 'Use it to see what a change actually did before deciding whether to roll it back.' It does not name alternative tools or list when-not-to-use conditions, so it falls short of a 5, but the intended scenario 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 indicate idempotence and non-destructiveness; the description adds genuinely useful behavioral facts beyond that: generation is deterministic in the seed and the reference solution is executed on this host to compute expected outputs. It does not describe persistence of generated files, but no annotation is contradicted.

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 dense sentences, front-loaded with the action and style requirements, followed by execution behavior. Every clause carries information and there is no filler.

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

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

Given the output schema, full parameter schema descriptions, and annotations, the description covers what is needed to invoke the tool and understand its output: style, determinism, and reference-solution execution. It could note whether generated hidden files persist, but that is minor given the structured fields.

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 four parameters at 100%, so the baseline is 3. The description adds a little semantic value by tying determinism to the seed, but it supplies no parameter-level syntax or constraints 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 names a specific verb ('Generate') and a specific resource ('one problem in Repovive's published house style'), and it lists concrete format details that separate it from generic generation siblings like repovive_generate_problem. It is not a tautology and communicates exactly what the tool produces.

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

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

The description establishes a clear context: use when a problem must follow the published house style, with t-led multi-tests, braced arrays, and sample packing. It does not explicitly name alternatives or exclusion conditions, but the context is unambiguous enough for an agent to select 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 beyond the idempotentHint annotation by clarifying that the same seed produces the same problem, and it discloses that test outputs are produced by running the reference solution on this host. This is meaningful behavioral context that annotations alone do not provide, though it does not explicitly describe persistence side effects.

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 carry a dense, front-loaded list of deliverables plus important behavioral notes. There is no filler, repetition of the schema, or explanatory padding; 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?

Given the output schema exists and the sibling context is complex, the description provides the essential facts an agent needs: what is generated, determinism, and that execution happens locally. It falls just short of fully complete because it does not say whether the result is persisted or how it connects to validation/judging workflows.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds value by explaining seed determinism and deterministic hidden tests. It explicitly connects the seed parameter to reproducibility, which helps the agent understand consequences of changing seed or num_hidden.

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

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

The description states a concrete verb and resource: generate a complete problem from a built-in generator, then enumerates exactly what is produced (statement, constraints, samples, tests, validator, editorial, solution). This is specific enough to distinguish it from sibling tools like repovive_generate_house_problem or the build_* problem-editing 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 implies when this tool is useful—when a full problem is needed from a generator—but it gives no explicit guidance about when to prefer it over alternatives such as repovive_validate_problem, repovive_judge_solution, or repovive_generate_house_problem. It does not state exclusions or prerequisites beyond pointing to repovive_list_problem_templates in the schema.

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 openWorldHint=true. The description adds valuable behavioral context by disclosing that the tool pages through the contest list until it finds a match, which explains why older contests resolve and implies potential performance characteristics. It also clarifies that the contest number is the one shown in the title.

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

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

Two sentences, front-loaded with the primary purpose and identifier options, followed by the paging behavior. Every clause earns its place and nothing is 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 simple two-parameter, read-only tool with an output schema and complete parameter descriptions, the description covers the essential invocation details. It could be slightly stronger about whether exactly one of contest_id or contest_number must be provided, but the schema and description together are 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 coverage is 100%, so the baseline is 3. The description adds a small but useful semantic detail: contest_number refers to the number shown in the title, reinforcing what the schema already describes. It does not add significant new meaning beyond that.

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

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

The description states a specific verb ('Fetch'), a single resource ('one contest's full record'), and the exact identifier options (contest number or ObjectId). The phrase 'full record' and 'one contest' clearly distinguish this from repovive_list_contests and repovive_get_contest_registrations.

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

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

The description implies the main use case: retrieve one specific contest by its number or ObjectId. It does not explicitly name alternatives or state when not to use this tool, though the identifier-focused framing gives reasonable context.

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 openWorldHint=true, so the description need not restate the safety profile. It adds useful context that the content is jury-posted and relevant to mid-round changes. It doesn't overpromise behavior and no contradiction exists.

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

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

Two tight sentences: the first states the action and resource, the second gives the practical trigger. No filler or 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?

This is a simple single-parameter read tool with a full input schema, output schema, and annotations. The description covers purpose and when-to-use, leaving nothing essential missing 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 description coverage is 100%: contest_id is fully documented as a 24-character hex ObjectId and required. The description adds no extra parameter-level detail, 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?

Description states a specific verb ('Fetch') and resource ('announcements and clarifications posted by the jury for a contest'). This clearly distinguishes it from sibling read tools like repovive_get_contest or repovive_get_contest_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?

Explicitly says when to use it: 'Check these when a statement is ambiguous or a problem was patched mid-round.' It gives clear context though it doesn't name an alternative tool; no sibling appears to be a direct substitute.

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 openWorldHint, and the description adds an eligibility precondition that affects call success. It could state what happens when invite is disallowed, 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?

Two concise sentences: the core purpose and the relevant routing guidance are front-loaded with no filler.

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

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

For a single-parameter read-only tool with an output schema and eligibility guidance, the description is complete. Nothing essential for calling it correctly is missing.

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

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

The schema fully documents contest_id as a 24-character hex ObjectId, so the description adds no additional parameter-level meaning. 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?

Clearly identifies the operation: fetching the shareable invite link for a contest. The conditional 'when the authenticated account is allowed to invite' adds precision and distinguishes it from related contest access 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?

Explicitly instructs the agent to use repovive_check_invite_eligibility first if unsure, naming the alternative and the condition. This is unambiguous routing guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations by specifying the required admin authorization and the exact role types returned (editor/viewer/admin). 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?

Two short sentences with no filler. The core purpose is front-loaded in the first sentence, and the authorization requirement is efficiently placed in the second.

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 one-parameter read-only tool with an output schema and safety annotations, the description is complete. It states the resource, the roles involved, and the necessary permission to call it, leaving no missing information needed for a 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 description coverage is 100% and the only parameter, contest_id, is already well documented as a 24-character ObjectId. The description does not add parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('which users hold editor/viewer/admin roles on a contest'), making the tool's function immediately clear. It also distinguishes itself from sibling mutation tools like set/remove_contest_permission and from generic get_contest.

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 by stating the authorization prerequisite: 'Requires the authenticated account to administer that contest.' It does not explicitly name alternatives or say when not to use it, but the role-listing scope and admin requirement are enough to guide selection among the closely related permission 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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral context with 'capped at the number of rows you ask for' and 'after a contest', but does not disclose details like default limit behavior or whether results are paginated.

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-loaded with the core action and return contents, followed by a usage hint. Every sentence earns its place with no filler.

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

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

Given the output schema exists and the input schema fully documents parameters, the description covers the essential purpose, fields, row cap, and timing. It is slightly incomplete in not differentiating this from repovive_get_leaderboard or repovive_get_contest_results, but it is otherwise sufficient for a low-complexity 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?

Schema description coverage is 100%, so the parameter meanings are already fully documented. The description adds only a general reference to row capping, which maps to the limit parameter, but provides no extra semantics beyond the schema.

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

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

States a specific verb and resource: 'Fetch a contest's standings' with the exact fields returned (rank, participant, country, total score). This is clear, though it does not explicitly distinguish itself from sibling tools like repovive_get_leaderboard or repovive_get_contest_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?

Provides clear context: 'Use it after a contest to see final placement.' This tells an agent when the tool is appropriate, but it does not explicitly state when to choose this tool over the similar-sounding siblings or mention exclusions.

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