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

With no annotations provided, the description carries the full burden. It explicitly discloses the four-stage validation pipeline, including destructive write protection and field whitelisting, which goes beyond a generic 'update' description. It does not detail error handling or return values, but the output schema presumably covers that.

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

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

The description is concise and front-loaded with the primary purpose, followed by a clear bulleted list of validation steps. Every sentence earns its place with no fluff 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?

Given the tool's moderate complexity and absence of annotations, the description covers the critical behavioral context (validation pipeline, write protection). The existence of an output schema handles return values. It stops short of mentioning force's role explicitly or potential error conditions, but overall it is sufficiently complete for an agent to select and invoke the tool safely.

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?

Although schema coverage is 100%, the description adds meaning by explaining that patch_json is subject to field whitelist, schema compliance, destructive write protection, and cross-field consistency checks. This helps an agent understand constraints on patch_json beyond the raw schema. The 'force' parameter is implicitly tied to the destructive write protection validation, adding contextual 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 opens with a specific verb+resource statement: 'Apply a validated normalized patch to update a single contest.' It clearly distinguishes this tool from siblings like bulk_apply_migrations (single vs. bulk) and update_document (contest-specific validation pipeline).

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 by emphasizing the validation pipeline and 'single contest' scope, which contrasts with bulk alternatives. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to differentiate from update_document and bulk_apply_migrations.

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 no annotations provided, the description carries the full transparency burden. It discloses a key behavioral trait: all patches go through 4 validations before writing, which is valuable for a bulk operation. However, it omits details about failure handling, atomicity, or the presence of destructive write protection (mentioned only in the schema for 'force'), leaving gaps in behavioral 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 concise and well-structured: the first sentence states the purpose, and the second adds a critical safety detail. There is no waste, and both sentences contribute meaningfully.

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

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

Given the tool's complexity (2 params, 1 required, output schema present), the description is minimally adequate but leaves gaps. It does not explain what happens if validations fail, whether the batch is atomic, or the implications of the 'force' bypass, which are important for a mutation tool of this nature.

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 both parameters ('migrations_json' and 'force') having descriptions in the input schema. The tool description does not add any extra meaning about parameters, focusing instead on the batch and validation aspects, so it stays at 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 clearly states the tool's function: 'Apply multiple migration patches in one batch (with validation)'. The verb 'Apply' is specific, the resource is 'migration patches', and the batch scope distinguishes it from the sibling tool 'apply_migration_patch'.

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: use this for applying multiple migration patches in a batch, and the mention of validation implies a safety-conscious workflow. However, it does not explicitly name an alternative or state when not to use it, so it lacks a full exclusion.

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 no annotations, the description carries full responsibility for behavioral disclosure. It only states the core mutation action ('create') without revealing side effects, such as whether an existing document is overwritten, what happens if the collection does not exist, or any security or error considerations.

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, concise sentence with no wasted words. It efficiently communicates the core purpose without unnecessary 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?

Although the parameters are fully covered by schema and an output schema exists, the description lacks essential context for an agent to invoke it correctly. It does not explain when to use create_document versus update_document, whether collections must exist, or any other operational prerequisites. Given the tool's simplicity and rich sibling set, this is a noticeable gap.

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

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

Schema description coverage is 100%, with both parameters (collection_name, document_json) clearly described. However, the tool description adds no additional 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 the action 'Create' and the resource 'a new document in a collection.' This specific verb+resource pair distinguishes it from sibling tools like update_document, delete_document, and get_document.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or any sibling tools, leaving the agent without context for selecting this tool over others.

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 no annotations provided, the description carries the burden of disclosing behavioral traits. It states the tool 'Check[s]' connectivity and returns database connection status plus any error message, implicitly indicating a read-only operation. It does not discuss side effects or permissions, but for a status-check tool, this level of disclosure is adequate.

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

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

The description is brief and front-loaded, with the core purpose in the first sentence and return values clearly listed. Every word earns its place, with no fluff 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?

For a zero-parameter tool with an output schema, the description fully covers intent and return behavior. The complexity is low, and the description provides enough context without needing to explain return values in detail since an output schema exists.

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 baseline is 4. The description does not need to explain parameter semantics, and no additional param-related information is required.

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

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

The description clearly states the tool's function: 'Check MongoDB connectivity separately from server health.' It uses the specific verb 'Check' with the resource 'MongoDB connectivity', and explicitly distinguishes it from server health, which differentiates it from the sibling health_check tool.

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 by noting this checks database connectivity 'separately from server health', implying it should be used when a MongoDB-specific status check is needed rather than a general health check. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, so it falls just short of a 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Delete', which is a basic action, but does not mention permanence, irreversibility, side effects, or permission requirements. This is minimal and adds little beyond the tool name.

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 is efficient and direct. It contains no fluff or redundancy, earning full marks for conciseness.

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 delete operation with fully documented parameters and an existing output schema, this description is adequate but not complete. It omits any caution about the permanent nature of deletion or potential consequences, which would be valuable for an agent. Still, given the simplicity, a score of 3 is reasonable.

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?

Input schema coverage is 100%, with both parameters described in the schema. The description does not add any extra meaning about parameters, but the baseline is 3 given the high schema coverage. No additional clarification is necessary.

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 ('Delete') and the resource ('a document from a collection'). It distinguishes from sibling CRUD tools like create_document, update_document, and get_document, making its purpose unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention scenarios for deletion or any exclusions (e.g., cannot delete if document is referenced elsewhere). This is a clear gap.

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 no annotations provided, the description carries the full behavioral burden. It discloses the read-only nature, case/punctuation/word-order normalization, the LIVE-only scope, and the nuance of same-source exact-title duplicates and their shadowing effect. This goes well beyond the minimum and gives the agent a detailed behavioral model.

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

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

The first sentence front-loads the core purpose and scope, while the second adds essential context about the duplicate gate and same-source shadowing without unnecessary fluff. Every sentence earns its place, and the overall length is appropriate for the tool's complexity.

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 audit tool, this description is comprehensive: it explains what it does, how matching works, the scope (LIVE only), and edge-case behavior (same-source shadowing). The output schema handles return structure, and the description adds necessary business context, making it 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?

The only parameter, min_live, is fully documented in the input schema with a description, default value, and the archived-ignored behavior. The description itself does not add any additional semantic context beyond what the schema already provides, so the baseline 3 for high schema coverage 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 opens with 'Read-only audit: find groups of LIVE contests that share the same normalized title', which clearly specifies the verb (find), resource (LIVE contests), and matching rule (normalized title). It distinguishes itself from sibling tools by focusing specifically on duplicate titles, a concept not present in any sibling name.

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 the tool by explaining these are records the duplicate-title gate would block on ingestion, and it also clarifies that same-source exact-title duplicates are included with an explanation of shadowing. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden. It clearly discloses the non-modification of Contests and that it only records the finding. However, it does not mention whether the tool appends or overwrites existing flags, nor does it detail any return behavior beyond what an output schema might cover.

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 compact and well-structured. It opens with a one-sentence purpose, then gives context on when to use it, and closes with a critical behavioral note. Every sentence adds value without redundancy, making it easy 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?

Given the tool's simplicity and the presence of an output schema (indicated in context), the description fully covers what an agent needs: purpose, invocation context, side-effect clarification, and a pointer to subsequent human steps. No significant gaps remain.

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 documented in the input schema. The main description does not add parameter-level meaning beyond the schema, so the baseline of 3 is appropriate. The schema's detailed example for discrepancies_json compensates well for any lack of description-level detail.

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: 'Flag a factual discrepancy found in CONTEST DATA during AI research.' It clearly distinguishes this tool from siblings like update_document or apply_migration_patch by stating it records findings to a separate collection and does not modify Contest data.

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

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

The description explicitly states the trigger condition: when a chatbot discovers a concrete, verifiable error during AI research. It also provides an exclusion ('This tool does NOT modify the Contests collection') and points to human review via other pipeline tools (apply_migration_patch, etc.), making usage boundaries 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?

With no annotations provided, the description carries the full burden. It does disclose the key behavior: returns a single prompt string that can be fed into any image model. However, it does not explicitly state whether the tool modifies any data (it appears to be a pure read/generation operation) or describe error conditions, which would be helpful for full transparency.

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 very concise, with just two sentences. The first sentence immediately states the main action, and the second provides necessary context about the output and usage. No unnecessary words 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?

For a simple tool with one parameter and an output schema, the description covers the core purpose, return value, and usage context. It does not elaborate on error cases or prerequisites, but given the tool's simplicity, this is adequately 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?

The schema has 0% description coverage for contest_id, so the description must compensate. The phrase 'by ID' clarifies that the parameter is a single contest identifier, but it adds no additional detail about the ID's format or source. The parameter name is self-explanatory, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Generate a premium image-generation prompt for one contest by ID.' It also specifies the output ('a single prompt string') and the use case ('when the original contest banner is missing'), which distinguishes it from sibling tools that list contests or verify URLs.

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 clear condition for use: 'when the original contest banner is missing.' It does not explicitly mention when not to use the tool or name alternative tools, but the context is sufficiently specific for an agent to select it appropriately.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context, such as the sorting priority order and that the response includes both the prompt text and contest documents. However, it does not explicitly state that the operation is read-only or idempotent, and it omits details about pagination behavior, though those are partially covered by the schema.

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

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

The description is concise, front-loaded with the core purpose, and each sentence adds value. It efficiently conveys what the tool returns, the priority order, and the intended subsequent action (sending to Mistral). No fluff or redundant information 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?

Given the tool's simplicity (2 optional parameters, read-only operation) and the presence of an output schema, the description is complete. It explains the purpose, the content of the response, and the priority ordering, providing sufficient context for an agent to invoke the tool correctly and know what to do with the results.

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

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

The input schema already provides 100% coverage for both parameters (`skip` and `batch_size`) with their descriptions. The tool description adds no additional parameter-level semantics beyond implying a batch of contests is returned. Therefore, the baseline score of 3 is appropriate; the schema handles parameter explanation.

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

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

The description clearly states the tool's function: returning contests that need AI-generated detail pages, sorted by priority. It distinguishes this from sibling tools by focusing specifically on detail generation and mentioning the prompt text inclusion. The specific verb 'Return' and resource 'contests needing AI-generated detail pages' leave no ambiguity about the tool's purpose.

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

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

The description gives clear context for when to use this tool: to fetch contests along with the prompt text and documents for sending to Mistral for detail generation. However, it does not explicitly name alternative tools or state when not to use it, though the purpose is distinct enough among siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses the selection behavior (contests missing category, prizeSummary, or feeConfidence) and pagination intent, but it does not explicitly state that the operation is read-only, nor does it mention potential empty results or error conditions. This is adequate but not deeply transparent.

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 short sentences, immediately conveying the main purpose, followed by a clear explanation of the selection criteria and pagination. There is no extraneous information, and the structure is front-loaded with the core verb and object.

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 retrieval tool with two self-descriptive parameters and an output schema, the description sufficiently covers why to use it (migration), what it returns (contests missing fields), and how to process in batches. It is complete and leaves no significant gaps for the agent to guess.

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 has 100% coverage with clear descriptions for skip and batch_size. The description adds only the general advice to use pagination, which does not significantly enhance the parameter semantics. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: getting a batch of existing contests needing migration to v4.0 schema. It specifies the resource (contests), the action (get), and the selection criteria (missing key fields), effectively distinguishing it from sibling tools like get_contests_missing_images or get_contests_for_detail_generation.

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: during migration to v4.0, specifically for contests missing key fields. It also advises using pagination for batch processing. However, it does not explicitly mention when NOT to use it or how it compares to alternative tools, though the unique 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It communicates that the tool is read-only ('Fetch') and specifies the filter condition, which is helpful. However, it omits behavioral traits such as pagination semantics, how empty vs. null URLs are handled, and any performance implications from large result sets.

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 exactly two sentences. The first sentence states the core operation, and the second adds a purpose. Every word earns its place, with no filler or 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 tool is simple, and an output schema exists, so return values need not be described. The description covers the core purpose and differentiates from a close sibling. However, the complete absence of parameter semantics in both description and schema lowers completeness slightly, though the parameter names are reasonably self-explanatory.

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 0%, and the description does not mention skip or batch_size at all. The parameter names are conventional, but no additional meaning is added in prose. Given the low schema coverage, the description should have compensated by explaining what these parameters control.

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 the specific verb 'Fetch' with the resource 'contests where the primary image URL is missing or empty,' which clearly states the exact condition. It also differentiates from the sibling tool get_contests_with_broken_images by specifying 'missing or empty' rather than 'broken.' The added purpose context ('identify documents that need AI-generated replacement banners') further clarifies intent.

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

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

The description explicitly states a use case: 'Use this to identify documents that need AI-generated replacement banners.' This gives clear context for when to select this tool. It does not explicitly mention alternatives or when not to use it, but the purpose statement is sufficient for an agent to understand when it applies.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It indicates a read-only fetch operation and the return purpose, but does not mention pagination behavior (despite skip/batch_size params), authentication requirements, or other side effects. The word 'Fetch' implies read-only, providing a moderate level of transparency.

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 consists of two concise sentences, front-loaded with the action and condition. Every sentence adds value without unnecessary filler, making it appropriately sized and well-structured.

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

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

Given the tool's simplicity and the presence of an output schema, the description sufficiently covers core behavior and purpose. It lacks parameter detail but is otherwise complete for this niche fetch operation, making it adequate for an agent to understand when and why to use 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?

The input schema lists skip and batch_size with defaults but no descriptions, and the tool description does not explain these parameters in context. With 0% schema description coverage, the description fails to compensate for the missing parameter semantics, leaving the agent to infer their meaning.

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 'Fetch' and the targeted resource 'contests' with a specific filter condition ('image.primary.status is marked as broken'). This distinguishes it from sibling tools like get_contests_missing_images, which addresses a different condition.

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 a clear context by explaining the intended use case: 'so the chatbot can display or re-generate banners'. While it does not explicitly mention alternatives or when not to use the tool, the specific condition implies a focused scenario, giving acceptable 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 no annotations, the description carries the full burden of behavioral disclosure. It only says 'Get' which implies read, but doesn't disclose behavior for missing documents, error handling, permissions, rate limits, or return format. Minimal behavioral information is provided.

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

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

One short sentence, front-loaded with the core action. No wasted words. It is concise and well-structured for a tool of this simplicity.

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 low-complexity tool with complete parameter schemas and an existing output schema, the description is nearly sufficient. It lacks guidance on edge cases or sibling comparisons, but the schema covers parameters and output, making it reasonably complete. Missing annotation context slightly reduces the score.

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 description adds no parameter information beyond the input schema, which already has 100% coverage with descriptive definitions for document_id and collection_name. Baseline 3 applies; the description provides no additional meaning.

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 ('Get') and resource ('document') with clear scoping ('by ID'), distinguishing it from collection-level reads like read_collection. It is unambiguous and tells the agent exactly what this tool does.

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 no when-to-use guidance or alternatives. It doesn't mention when to use this over read_collection or other get_* tools, nor when not to use it. The phrase 'single document by ID' implies usage, but no explicit guidance is given.

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 no annotations, the description carries the full burden. It details the computed metrics (live events, events with details by status, without details, coverage percentage) and lists the return dictionary fields. While it doesn't explicitly say 'read-only,' the status-oriented language and the verb 'get' imply no side effects. It could add a note on permissions or side effects, but the lack of such is not a major gap for a status tool.

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

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

The description is concise and well-structured: a one-sentence purpose, a short explanatory paragraph, a usage line, and a Returns section. Every sentence earns its place, and the front-loaded main clause ensures quick comprehension.

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 status tool with no parameters and an output schema, the description is complete. It explains what the tool does, how to use it in a workflow, and what it returns. The output schema formalizes the return structure, so the description's explanation of the dictionary fields is sufficient and even redundant in a helpful way.

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 takes zero parameters, so there is nothing for the description to add beyond what the schema already shows (an empty object). Per the baseline for 0 parameters, a score of 4 is appropriate; no further parameter explanation 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?

The description opens with 'Get coverage metrics for the event detail generation pipeline,' clearly identifying the specific resource and the action. It distinguishes from sibling tools like get_events_for_detail_generation by focusing on status instead of fetching work items, making its purpose unambiguous.

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

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

It explicitly states when to use this tool: 'Use this to see how much event-detail work remains before deciding how many batches of get_events_for_detail_generation to run.' This names the alternative tool and provides clear decision context, satisfying the dimension fully.

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?

No annotations are provided, so the description carries the burden. It implies read-only behavior through the verb 'Read' and 'query', but does not disclose details like default pagination, ordering, or side effects. This is adequate but not rich.

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

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

Two sentences with no redundancy. The first states the core function, the second gives actionable examples. 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?

Given the schema covers all parameters and an output schema exists, the description is sufficient in conveying purpose and usage context. It could mention default behavior when no filters are applied, but this is a minor 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 coverage is 100%, which sets a baseline of 3. The description adds value by showing how filters combine in real scenarios (e.g., 'all upcoming conferences' maps to upcoming_only and event_type, 'draft status' maps to status), going beyond the isolated schema descriptions.

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

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

The description clearly states the tool reads structured events from the Events collection with filtering capabilities. It provides concrete examples (upcoming conferences, draft status) that make the purpose immediately understandable and distinguish it from write/update 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 recommends use for querying pipeline-harvested events and gives two practical use cases. However, it does not mention any alternatives or exclusions (e.g., when to use get_events_overview instead), so it misses the full criteria for a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the response structure (prompt text + event documents) and the sorting priority order. As a read operation implied by 'get', no side effects are mentioned but none are expected. It lacks explicit read-only confirmation, but the name and content cover the essentials.

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

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

The description is concise and well-structured: a one-sentence purpose, a note on the response payload with a usage instruction, and a clear priority order. Every sentence earns its place with no 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?

The tool has an output schema, so return values are documented. The description explains the selection criteria (priority order) and how to use the results (feed both prompt and events to LLM). This is complete for a retrieval tool with two simple parameters.

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

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

Schema description coverage is 100%, with both 'skip' and 'batch_size' fully described. The description adds no additional parameter meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific action: 'Return events needing AI-generated detail pages'. This distinguishes it from sibling tools like get_events (general listing) and get_contests_for_detail_generation (contests, not events). The priority order further clarifies the scope.

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: it is for fetching events that require AI-generated detail pages, and it instructs to send both prompt text and event documents to the LLM. It does not explicitly name alternatives or exclusions, but the 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?

No annotations are provided, so the description carries the full burden. It discloses the return structure (a dictionary with counts by eventType/status and upcoming events) and the read-only, overview nature of the tool. While it doesn't mention permissions or edge cases, the simplicity of a zero-parameter overview tool makes this adequate.

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

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

The description is concise and front-loaded: it states the purpose in the first sentence, then explains what is returned and offers a usage hint. The separate 'Returns' line is redundant but not wasteful. 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 zero-parameter tool with an output schema, the description fully covers the essential aspects: purpose, return content, and when to use it. It is complete and appropriately scoped to the tool's simplicity.

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 baseline is 4. The description adds no parameter details, but no parameters exist to explain. The schema is empty and additionalProperties is false, so there is nothing else to clarify.

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 provides a 'quick overview of the Events collection' and specifies the exact breakdowns returned (counts by eventType/status, number of upcoming events). This distinguishes it from sibling tools like get_events or get_events_for_detail_generation, which focus on retrieving or processing event data rather than summarization.

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 a clear usage context: 'Use this to decide what to review or process next.' This tells the agent when to choose this tool for high-level assessment. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses the return type (dictionary with migration progress and field breakdown) but does not explicitly state that this is a read-only operation or mention any prerequisites. The behavior is mostly evident from the name, but the description adds only output details, not deeper behavioral context.

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 short sentences, each contributing meaningful information: purpose, specific details, and return value. It is front-loaded with the main action and avoids redundancy or fluff.

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

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

Given the tool's simplicity (0 parameters, output schema exists, no nested objects), the description fully covers the necessary context. It explains what the tool does, what it reports, and what it returns, making it self-sufficient for an agent to select and invoke 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?

The tool has zero parameters, and the schema coverage is 100% (empty object). Per the rubric, a description for a 0-parameter tool gets a baseline of 4, and no additional parameter explanation is needed. The description accurately reflects that no arguments are required.

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

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

The description clearly states the tool's purpose: 'Get overall migration progress statistics for the 810 contests.' It specifies exactly what it reports (migrated/pending/missing fields), which distinguishes it from sibling tools like get_contests_for_migration or apply_migration_patch.

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

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

Usage context is implied ('overall migration progress statistics' suggests use for high-level status), but the description does not explicitly mention when to use this tool instead of related siblings like get_contests_for_migration or database_status. No exclusions or alternatives are named.

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

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

With no annotations provided, the description must carry the full burden. It implies a read-only operation through 'Return' and mentions the raw nature of the data, but does not explicitly state side-effect absence, rate limits, or payload size considerations. The use case is described, but deeper behavioral traits are not disclosed.

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

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

The description is concise, two sentences total, with the purpose front-loaded in the first sentence and the use case in the second. Every sentence earns its place, with no redundant or verbose phrasing.

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 provides sufficient context for a simple retrieval tool, especially given that an output schema exists to explain return values and a fully documented input schema. However, it could mention that the tool is read-only or note likely large response sizes, but these are minor gaps given the overall clarity.

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 parameters are well-documented. The description adds no specific parameter details beyond what the schema already provides, such as 'skip', 'batch_size', or 'prompt_name' defaults. The mention of 'prompt text' and 'contests' indirectly relates, but does not enhance 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 tool 'Return the prompt text together with contest documents for AI processing', using a specific verb and resource. It distinguishes itself from sibling tools by explicitly combining prompt text with raw MongoDB contests, which is a unique purpose.

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

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

The description provides an explicit when-to-use scenario: 'Use this when Claude or ChatGPT needs both the instructions and the raw MongoDB contests in a single response so it can normalize them locally.' It does not mention exclusions or alternatives, but gives clear context for appropriate use.

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?

No annotations are provided, so the description carries the burden. It discloses the source filtering behavior but does not explicitly state that it is a read-only operation or mention any performance or side-effect characteristics. The phrase 'Return a summary' implies read-only, but more explicit disclosure would be better.

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, no redundant language. 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?

The description is sufficient for a simple status tool with one optional parameter and an output schema. It covers purpose and parameter behavior. The output schema covers return structure, so the description does not need to list 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?

The schema has zero parameter descriptions, but the tool description thoroughly explains the `source` parameter, giving examples and explaining that it limits results to records from that scraper. This compensates well for the lack of schema-level documentation.

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

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

The description clearly states it returns a summary of raw scraped data in CHRawdata.rawdata, a specific resource, and mentions optional source filtering. This distinguishes it from other status tools like database_status.

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

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

The description establishes a clear context for use: checking what raw scraped data is available, optionally for a specific scraper. It does not explicitly name alternatives or exclusions, but the usage scenario 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?

No annotations are provided, so the description must carry the burden of behavioral disclosure. The verb 'Claim' implies marking documents as claimed, but the description does not state whether this is a mutating operation, if it is reversible, or what happens to unclaimed records. It only mentions that the chatbot uses its own web search, leaving significant ambiguity about 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?

The description is three sentences, each serving a distinct purpose: core function, sibling differentiation, and behavioral context. It is tightly written with no filler, front-loading the primary action.

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 an output schema and simple two-parameter input, and the description explains the purpose, usage stage, and verification approach. However, it omits important side-effect details of the 'claim' operation, such as whether claiming prevents other agents from accessing these records and what happens in case of failure. Given the output schema, this is acceptable but not perfect.

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

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

Both parameters are fully described in the schema (100% coverage), including defaults and maximums, so the description adds little beyond what the schema provides. The mention of the chatbot's own web search contextually relates to chatbot_id but does not add extra semantics. Baseline 3 is appropriate when the schema fully documents parameters.

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

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

The description clearly states it 'Claim a batch of unvalidated contest documents and return them with a validation prompt,' using a specific verb and resource. It distinguishes itself from get_records_for_validation by specifying it works on the Contests collection.

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

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

The description provides explicit usage context: 'Use this for Stage 2 validation before LLM normalization' and mentions similarity to get_records_for_validation while targeting the Contests collection. This gives clear when-to-use guidance, though it does not explicitly list exclusions for 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?

No annotations are provided, so the description carries the full burden. It discloses the fetch operation and the workflow, and implies read-only behavior, but does not explicitly state side effects, rate limits, or constraints beyond what the schema covers.

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 moderately concise, with a clear first sentence and a numbered workflow. The step-by-step instructions add value but could be tightened.

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 description provides a full workflow with the expected interaction with submit_structured_events, it is quite complete. It could mention the limit on records, but that's in the schema.

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

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

Schema coverage is 100%, so the schema already documents all three parameters with descriptions. The tool description does not add any parameter-specific meaning, but it does not need to.

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

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

The description clearly states the tool fetches raw records plus an events structuring prompt, using specific verbs and resources. It distinguishes itself from siblings by focusing on participatory events and the events-v1.1 schema.

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

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

It explicitly states 'Use this when you want to go from raw event URLs/titles to a structured event document in one AI round-trip' and provides a step-by-step workflow. It does not explicitly name alternative tools or when not to use it, 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?

With no annotations, the description carries the full burden. It discloses the multi-step workflow (reading prompts, searching the web, extracting, researching, generating) and the intended follow-up via submit_full_generation. However, it doesn't mention potential side effects, rate limits, or external network dependencies explicitly, so it's not a 5.

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

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

The description is longer than minimal, but the numbered list structures the workflow clearly and every sentence contributes to understanding how to use the tool. A bit verbose but not 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?

Given the tool's complexity and that an output schema exists, the description adequately covers the overall process, expected inputs, and the next step. It could mention error scenarios or prerequisites more explicitly, but it's complete enough for a capable agent.

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

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

Schema description coverage is 100%, so each parameter is already well-documented. The description adds workflow context but doesn't add new parameter-specific semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Fetch') and resource ('raw scraped records + BOTH prompts') and clearly distinguishes this tool from siblings by combining structuring and detail generation in one pass. It also names the exact prompt files involved, making the purpose unmistakable.

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 use this when a single AI round-trip from raw data to published contest details is desired. It doesn't name alternative sibling tools (e.g., get_records_for_structuring) but implies them by contrast, so clear context is provided without explicit exclusions.

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

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

With no annotations, the description carries the behavioral burden. It states that it fetches raw records and the prompt, implying a read-only operation. However, it does not mention side effects, authorization, or record readiness for structuring, so some behavioral gaps remain.

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 fluff. It packs the key elements: action, resource, prompt version, schema version, and target format.

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 essential purpose and identifiers (prompt version, schema, output format). With an output schema present, return values are already defined elsewhere. It could improve by noting when to use this over sibling tools, but it is otherwise complete for a fetch operation.

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 described in the schema. The description adds no additional parameter-specific context, thus 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 uses a specific verb ('Fetch') and clearly identifies the resources ('raw scraped records + the structuring prompt'). It differentiates from siblings by mentioning the exact prompt file and 'normalized Contests format', making it distinct from event/validation/similar tools.

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

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

The description provides clear context: this is for structuring records into the Contests format. It implies use for structuring workflows but does not explicitly list alternatives or when-not conditions, so it falls just short of a 5.

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

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

With no annotations, the description carries full responsibility. It discloses the key side effect: records are atomically marked as 'in_progress' for the given chatbot_id, preventing others from claiming them. It also explains that the returned records are meant for a chatbot with its own web search capability. This covers the most important behavioral trait (state change) beyond what annotations might 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 three sentences and about 50 words. It is front-loaded with the core action and efficiently explains the purpose and side effects. The second sentence about the chatbot's web search is useful context, though slightly tangential to the tool's own behavior, but 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 presence of an output schema (which likely describes returned records and the validation prompt), the description need not explain return values. It adequately covers the claiming behavior, the atomic state change, and the intended workflow. It could mention edge cases like what happens when no records are available, but that is not a major 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?

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description doesn't add much parameter-specific detail beyond the schema, except that records are marked for the given chatbot_id, which aligns with the schema's note about using different IDs for parallel processing. This is marginal added 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 claims a batch of unvalidated raw records and returns them with a validation prompt. It uses a specific verb ('claim') and resource ('raw records'), and distinguishes from sibling tools like get_records_for_structuring by focusing on validation for a chatbot.

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 (for chatbot validation via web search, claiming unvalidated records) and mentions the atomic in_progress marking to prevent duplicate claims. It implicitly distinguishes from alternatives for other workflows (structuring, events), but doesn't explicitly name alternatives or say when not to use.

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?

No annotations are provided, so the description carries the full burden. It discloses the return contents (counts, validation status, dates, sample titles) and positions it as 'quick' and 'actionable,' but it does not mention potential edge cases, performance implications, or whether any filtering is applied beyond the optional source parameter. This is adequate but not deep.

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, front-loaded with the main purpose, followed by use context and return details. Every sentence adds value; 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?

Given an output schema exists, the description doesn't need to enumerate return values in detail, but it does anyway, which is helpful. It gives enough context for an agent to decide when to invoke it among many siblings, though it doesn't contrast with alternatives. This is slightly above the minimum.

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 covers the optional 'source' parameter with examples, so the description does not need to add parameter meaning. The description doesn't mention the parameter at all, but the schema handles it, warranting the baseline score 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?

Description opens with a specific verb+resource: 'Get a quick, actionable overview of what raw scraped records are available.' It clearly distinguishes itself from siblings like get_raw_data_status by focusing on the overview of raw scraped records, and lists exactly what the overview contains.

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 states when to use it: 'Use this to see what's in the pipeline before deciding which source to work on.' This provides clear context, though it does not name alternative tools or exclusion criteria, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states 'without claiming any records,' implying a safe, read-only operation, and clarifies that it previews instructions. This adds meaningful context beyond the schema.

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

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

The description is two sentences, front-loaded with the primary purpose and key behavior. Every word earns its place; there is no redundancy or extraneous 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 tool is simple: one optional parameter fully documented in schema, and an output schema exists. The description explains what it does, its non-mutating behavior, and when to use it, leaving no significant 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 description coverage is 100%, fully documenting the two allowed values ('raw' and 'contest'). The tool description does not add parameter details, but the schema carries the load, so a baseline of 3 is appropriate.

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

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

The description states 'Preview the validation prompt without claiming any records,' which clearly identifies the verb (preview) and resource (validation prompt). It also distinguishes from sibling validation/submission tools by explicitly noting it does not claim records.

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 says 'Use this to see the instructions that will be sent to the chatbot before starting the validation workflow,' providing clear context for when to invoke the tool. However, it does not explicitly name alternative tools 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?

No annotations are provided, so the description must carry the full burden. It describes the output shape (counts by status) and the optional source filter. The verbs 'Get' and 'Shows' imply a read-only operation, but it does not explicitly state that no data is modified or discuss performance/data freshness. For a status-monitoring tool, this is mostly 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?

Three sentences: purpose, output details, and usage guidance. Every sentence earns its place, the key verb is front-loaded, and there is no redundant or vague 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 tool with one optional parameter and an output schema, the description fully explains what the tool does, what data it presents, and when to use it. It names the decision action (process_raw_data), making it complete for the tool's complexity.

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

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

The schema describes the single parameter 'source' with 100% coverage ('Optional scraper source to filter by'). The description adds that results are 'broken down by source if specified', giving extra semantic meaning about the grouping behavior that goes 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 opens with 'Get an overview of the validation pipeline status,' using a specific verb and resource. It enumerates the exact status categories shown (pending, in progress, validated, failed, skipped) and mentions source-based breakdown, clearly distinguishing it from sibling tools like get_raw_data_status or get_records_for_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 final sentence explicitly says 'Use this to monitor progress across multiple chatbots and decide when to run process_raw_data.' This provides a clear use case, ties to a sibling tool, and offers actionable guidance on when to invoke 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?

No annotations are provided, so the description carries the full burden. It discloses the return type (Dictionary with health status and metrics) which adds useful context beyond the input schema, but it doesn't specify details like required permissions, side effects (or lack thereof), or the semantics of 'health status' beyond generic metrics.

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, front-loaded with the purpose and followed by the return value. Every word earns its place with 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?

Given the tool's simplicity (no parameters, output schema present), the description is sufficient. It states the action and the return shape, which is complete for a health-check tool even though it doesn't enumerate every possible metric.

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 schema coverage is 100%, so there is no parameter detail needed. Per the baseline for zero-parameter tools, the description does not need to compensate, and the description doesn't mislead.

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 'Check the health status of the MCP server process.' It uses a specific verb and resource, and the mention of 'MCP server process' distinguishes it from sibling tools like database_status.

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

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

The description implies usage as a health check but gives no explicit guidance on when to use this tool versus alternatives such as database_status. There are no exclusions or alternative tool references, so context is only 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?

With no annotations, the description carries the full burden of disclosing behavior. It mentions the read-normalize-deduplicate-upsert flow and the validation gate, but does not explain the side effects of upserting (e.g., overwriting existing records), permissions required, idempotency, or failure behavior. This leaves meaningful gaps for a mutating operation.

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 plus a note, front-loaded with the core action and resource. Every sentence earns its place: the first states the operation, the second provides a critical default and prerequisite. No fluff.

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

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

The description is complete for a batch-ingestion tool: it names inputs, outputs, and workflow order. The output schema exists, so return-value documentation is not required. The only missing context is around operational safety (e.g., reversibility, potential data loss) and error handling, but these are not essential for an agent to 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%, so the schema already documents all four parameters. The description adds only mild context (e.g., that `source` is a scraper name and that upsert happens), but does not materially enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool reads validated raw records, normalizes, deduplicates, and upserts them into a specific collection (ContestHopperDb). It names the source table (CHRawdata.rawdata) and the target, distinguishing it from the many sibling tools that deal with validation or other processing steps.

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

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

The description explicitly says to run get_records_for_validation + submit_raw_validation first, providing a clear prerequisite. It also notes the default behavior of only processing records with validationStatus='validated', which tells the agent when this tool is appropriate.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Read documents' which implies read-only, but it does not explicitly state that it does not modify data, nor does it disclose behavior like error handling, collection existence requirements, or performance implications. The mention of filtering and pagination is already evident from the schema and adds little beyond it.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core action, target resource, and key capabilities 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 that the output schema exists and the input schema fully describes parameters, the description need not explain return values or parameter syntax. It is sufficient for a straightforward read tool, though it could be slightly more complete by noting any unique behaviors or prerequisites. Still, the provided schema and description together cover the essential context.

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

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

Schema description coverage is 100% for all five parameters, so the schema already fully documents each parameter. The description's reference to filtering and pagination adds minimal semantic value beyond what the schema provides, which aligns with the baseline score 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 clearly states the tool reads documents from a MongoDB collection with filtering and pagination, using a specific verb and resource. However, it does not distinguish itself from similar siblings like read_raw_collection or get_document, so it stops short of full differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives such as get_document or read_raw_collection. It only states what it does without any context on selection criteria or exclusions.

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

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

No annotations are provided, so the description carries the burden of disclosing behavior. It indicates a read operation and mentions filtering/pagination, but it does not explicitly state that it is read-only, potential side effects (though unlikely), or any auth/rate limit considerations. It adds context about the raw scraped data, but could be more explicit.

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 concise sentence that front-loads the action ('Read documents'), specifies the resource ('CHRawdata database'), and mentions key features. Every word earns its place with no 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?

The tool has a full schema and an output schema, so the description does not need to explain return values. It covers purpose and basic behavior effectively. However, it lacks explicit usage guidelines compared to alternatives, so it is not fully complete for guiding an agent on when to use 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?

The schema has 100% coverage with detailed descriptions for all parameters. The description mentions 'filtering and pagination' which loosely maps to filter_query, skip, limit, and sort_by, but it adds no additional detail beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool reads documents from the CHRawdata database (raw scraped data) with filtering and pagination. It distinguishes itself from the sibling 'read_collection' by specifying the specific database, making the purpose unambiguous.

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

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

The description implies usage for raw scraped data but does not explicitly state when to use this tool over alternatives like 'read_collection'. There is no mention of when not to use it or exclusions, leaving the guidance somewhat 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?

No annotations are provided, so the description carries the burden. It discloses that details are validated for quality, saved, and automatically versioned. It doesn't mention failure behavior, permissions, or idempotency, but the main workflow is transparent enough.

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 purpose and then add essential workflow context. Every clause earns its place with no fluff or repetition of schema fields.

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

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

With an output schema present, return values are already covered. The description explains the validation, storage, and versioning enough for an agent to select and invoke the tool. It could mention integration with the generation flow (e.g., after get_contests_for_detail_generation), but that's not necessary.

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

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

Schema description coverage is 100%, with both parameters explained in the schema. The description adds no additional parameter-level detail, but the baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description uses a specific verb 'Submit' and clearly identifies the resource ('AI-generated contest details') and destination ('contest_details collection'). It distinguishes from sibling tools by specifying contest details rather than events or records.

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: this tool is for submitting AI-generated contest details for validation and storage. It doesn't explicitly name alternatives or exclusions, but the scope is obvious and it differentiates from sibling submission 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 are absent, so the description carries the full burden. It discloses that the tool updates the Contests collection and targets existing contest documents, indicating a mutation. However, it does not explain whether prior validations are overwritten, whether the operation is idempotent, or any prerequisite beyond 'existing' documents. The reference to submit_raw_validation gives a baseline but without that tool's description, behavioral details remain 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?

The description is two short sentences: a clear purpose statement and a usage directive with sibling differentiation. There is no filler, and the key information 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?

Given only two well-documented parameters and an output schema, the description provides sufficient context: what the tool does, when to use it, and how it differs from the sibling. The main gap is behavioral detail (e.g., overwrite semantics, idempotency), but for a submit operation this is reasonably 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 coverage is 100%, so the baseline is 3. The description's phrase 'validation results from a chatbot' aligns with the validation_json parameter but adds no new meaning beyond the schema's own descriptions. The chatbot_id parameter is similarly self-explanatory, and the description does not elaborate on parameter format or restrictions.

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 submits validation results for contest documents, using the specific verb 'submit' and resource 'contest documents'. It also distinguishes itself from the sibling submit_raw_validation by noting it updates the Contests collection, making the purpose unambiguous.

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

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

The description explicitly says 'Same as submit_raw_validation but updates the Contests collection' and 'Use this for Stage 2 validation before LLM normalization', providing clear when-to-use guidance and naming an alternative tool. This meets the highest bar for usage differentiation.

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 no annotations provided, the description carries the full burden and goes well beyond basics. It discloses concrete validation rules (minimum word count, honest readingTime, no first-person, no hallucinated URLs) and states the outcome: saved to the event_details collection with automatic versioning. This is substantial behavioral context, though it omits failure handling or return specifics.

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

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

The description is concise and well-structured: a single clear opening sentence followed by a second sentence that adds relevant validation and storage details. Every sentence earns its place, with no redundant or vague 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 existence of an output schema (which covers return values) and only two well-documented parameters, the description is reasonably complete. It conveys the purpose, validation process, storage target, and versioning behavior. It lacks explicit prerequisites (e.g., event must exist) but the schema's required event_id covers that. Overall, it is sufficient for an agent 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 coverage is 100% with both parameters described in the schema, so the baseline is 3. The description adds minimal extra meaning—mainly that details_json is AI-generated and validated—but does not explain syntax or additional constraints beyond what the schema already provides. Thus, it meets the baseline without exceeding 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 a specific verb ('Submit') and resource ('AI-generated event details') with the additional scope of validation and storage. It distinguishes itself from sibling submit tools by explicitly mentioning event details and quality checks, which differentiates it from submit_contest_details or submit_structured_records.

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 the tool: when submitting AI-generated event details for validation and storage. However, it does not explicitly mention alternatives or when not to use it, such as comparing with submit_structured_events. This is clear but lacks exclusions, matching a 4.

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?

No annotations are present, so the description carries the full burden. It specifies required JSON structure and schema versions, adding some transparency, but doesn't disclose side effects, error behavior, or reversibility—significant omissions for a submission tool.

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 compact and front-loaded, with a clear purpose sentence and a bulleted structure. Every sentence adds value, making it highly concise with no wasted words.

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

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

An output schema exists, so return values are covered. The description covers the prerequisite and input format, but doesn't mention validation errors or failure modes. For a submission tool with a straightforward API, this is reasonably 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 coverage is 100%, so the baseline is 3. The description adds value by referencing v4.0 schema and contest-details-v1.0.txt, and by showing the items array structure, which exceeds the schema's simple 'structured contest object' phrasing.

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

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

The description states a specific verb+resource ('Submit a full generation result') and distinguishes it from other submit tools by emphasizing BOTH structured contest data and contest details in one call. It also references the predecessor tool, making its purpose unambiguous.

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

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

It explicitly instructs to use after get_records_for_full_generation, providing a clear workflow context. However, it doesn't mention when not to use it or alternatives, so it falls short of full exclusions.

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

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

With no annotations, the description carries the burden. It discloses the main behavior: processing JSON and updating each record's validation status. However, it omits important details such as whether existing statuses are overwritten, how invalid JSON is handled, or any idempotency guarantees. This is adequate but not comprehensive for a mutation tool.

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

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

The description is concise and well-structured: a clear opening sentence, then a brief workflow explanation. Every sentence provides necessary context without 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?

Given the presence of an output schema and well-described parameters, the description is largely complete for the main workflow. It explains how to use the tool and what it does, but lacks edge-case behavior like rejection reasons or side effects. Overall, it is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a little context by mentioning the workflow with get_records_for_validation, but it does not meaningfully elaborate on the validation_json structure beyond what the schema already states. It earns the baseline score.

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

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

The description clearly states the tool's purpose: to submit validation results from a chatbot for raw scraped records. It names the specific workflow (via get_records_for_validation) and distinguishes itself from sibling tools like submit_contest_validation by targeting 'raw scraped records'.

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 clear context on when to use the tool: after a chatbot has received records via get_records_for_validation and validated them. It implies a specific sequence but does not explicitly exclude alternative tools like submit_contest_validation, so it lacks a when-not 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?

With no annotations provided, the description fully carries the behavioral burden. It discloses deduplication key, upsert-in-place behavior, the duplicate-title gate with its default and effect, applied defaults, enum downgrade behavior, and metadata stripping — all beyond what the schema conveys.

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 well-organized with a short summary followed by bullet points for key behaviors. It is concise for the complexity it covers, though the phrase '(see details)' hints at external info that isn't provided inline, slightly reducing self-contained clarity.

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

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

Given the tool's complexity (deduplication, gating, defaults, enum handling, metadata), the description covers all major behaviors. An output schema exists, so return value documentation is not needed. The description is complete enough for an agent to use 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 coverage is 100% and the schema descriptions are already detailed for every parameter. The description adds little new parameter-specific meaning; it mostly restates the schema, so a baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Submit structured event records... and persist them to the Events collection.' It also distinguishes itself from the sibling submit_structured_records by calling itself 'the event counterpart,' making its scope unmistakable.

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 names the counterpart tool, which conveys when to use this vs. that (events vs. records). However, it does not detail when not to use it or provide alternative scenarios, 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?

No annotations are provided, so the description carries the full burden. It thoroughly discloses the upsert behavior, validation, deduplication key, the optional duplicate-title gate, skip/report behavior for duplicates, and the same-source exact-title update path.

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

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

The description is two tight paragraphs, front-loaded with the core action and then detailing dedup logic. Every sentence contributes meaningful information with no redundancy or fluff.

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

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

Given the moderate complexity, an output schema exists, and the schema covers parameters, the description is complete: it covers what the tool does, validation, upsert, dedup rules, and the gate behavior. No critical behavioral gaps are apparent.

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 both parameters are already well-described. The description adds value by explaining the deduplication key and the practical effect of the dedupe_gate parameter, which enriches understanding beyond the schema.

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

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

The description clearly states the tool's verb ('Submit'), resource ('structured contest records'), and outcome ('upserts into the Contests collection'), while referencing the exact schema. It distinguishes from siblings by specifying contest records rather than events or other data types.

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: records are produced by a chatbot and follow a specific schema, and the deduplication key links it to process_raw_data. However, it does not explicitly mention when not to use this tool or name alternatives like submit_structured_events.

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 no annotations provided, the description carries full responsibility for behavioral disclosure. It states only that it updates an existing document, but does not disclose whether it performs partial updates (e.g., $set), what happens if the document is not found, whether the operation is atomic, or any permission requirements. This is a significant gap for a mutation tool.

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, clear sentence with no unnecessary words and front-loads the action. It is appropriately concise, though it is so minimal that it under-specifies the tool's behavior, which is more a completeness issue than a conciseness issue.

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 a simple update operation, but the description lacks crucial contextual details: the semantics of the update (partial vs full replacement), error handling when the document doesn't exist, and return value expectations (though an output schema exists). Given the presence of a schema and output schema, the description should at least clarify the update behavior to be minimally 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?

The input schema describes all three parameters (collection_name, document_id, update_json) with 100% coverage, so the baseline is 3. The description adds no additional meaning about the parameters beyond what the schema already provides, but that is acceptable given the schema's completeness.

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 'Update' and identifies the resource as 'a document in a collection', which clearly distinguishes it from sibling tools like create_document, delete_document, and get_document. However, it lacks any qualifiers about the update mechanism (e.g., partial vs replace) that would add precision, so it is clear but not fully differentiated.

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 no guidance on when to use this tool versus alternatives. There are no exclusions, prerequisites, or alternative tool mentions. The sibling list includes create_document, delete_document, get_document, and read_collection, but the description doesn't differentiate beyond the basic action.

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 no annotations provided, the description carries full responsibility for disclosing behavior. It clearly states that it performs HTTP HEAD/GET, updates image.primary.status to 'active' or 'broken', and returns a report. This gives good insight into side effects and actions, though it does not mention potential external network calls' impact or rate limits explicitly.

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

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

The description is compact and front-loaded: the first sentence gives the core purpose, and the second expands with necessary technical details. Every sentence earns its place, with no redundancy.

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

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

Given the tool's simplicity, the presence of an output schema (covering the report), and the description's coverage of scanning, verification method, status update, and return value, the description is sufficiently complete. It provides all essential context for an agent to use 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 0%, and the description does not explain the three parameters (skip, batch_size, user_agent). The parameter names are somewhat self-explanatory, but the description adds no value for understanding their syntax, defaults, or interplay, which is a clear gap.

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 ('Verify') and resource ('image URLs for contests') and distinguishes it from read-only siblings like get_contests_with_broken_images by mentioning the database update. The purpose is unmistakable.

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 appropriate usage by specifying the exact scope (contests with image.primary.url) and the action performed. It does not explicitly name alternatives or exclusions, but the context is clear enough to guide an agent.

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