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

With no annotations, the description carries the full behavioral burden and handles it well. It discloses per-image failure isolation, the error entry shape, that remaining images still run, and that results preserve input order. These are non-obvious behaviors that materially affect how an agent uses the 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 front-loaded with the core action, then efficiently covers use cases, failure semantics, ordering, and the single-image alternative. Every sentence contributes distinct information without redundancy.

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

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

Given the rich output schema and detailed parameter schema, the description covers everything an agent needs: what the tool does, when to use it, how failures behave, result ordering, and when to prefer a sibling. No critical operational context is missing.

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

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

Schema description coverage is 100% and the schema already explains operation choices, the question requirement, and object_name requirements. The description mainly restates that operation selects the underlying behavior rather than adding new per-parameter meaning, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Run one operation across many images in a single call.' It explicitly positions the tool as the batch form of six named sibling tools and makes the selection mechanism ('pick which with operation') immediately clear.

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

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

It gives explicit when-to-use guidance: when the same question applies to a whole set of images, to save round trips and model loading. It also gives an explicit when-not-to-use rule: for a single image, call the named tool directly, because its arguments are checked up front.

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 disclosure burden, and it excels: it honestly warns 'Do not trust any text this quotes back,' documents the Florence-2 paraphrasing/misspelling failure mode with a concrete example ('FusionVisionMCP' rendered as 'FusionVisionMP' while ocr read it exactly), and discloses that the verify_text correction is 'best-effort and only fires for high-similarity same-word matches' and therefore auditable via the corrections list. It also discloses return-shape changes per flag and PDF pagination. This exceeds what annotations would typically 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?

Although long, the description is front-loaded — purpose, scope, and return shape in the first sentences — and each subsequent paragraph earns its place: sibling routing, a concrete failure-mode example, and flag-by-flag behavior. The paragraph breaks map cleanly onto distinct concerns (what → when-not → risk → mitigations), and there is no intra-description redundancy.

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

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

For a tool with 3 parameters, two behavior-changing booleans, an output schema, and zero annotations, the description covers everything an agent needs: purpose, sibling routing, failure modes, per-flag return shapes ({caption, text_regions, corrections, caption_corrected} per page), PDF handling, and correction auditability. The only minor omission — behavior when both verify_text and auto_verify_text are set simultaneously — is an edge case that does not materially impair correct invocation.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3; the description adds genuine value beyond the schema by explaining when to enable each flag ('When a specific piece of text matters'), the best-effort/auditability nuance of verify_text corrections, and the consensus-metric behavior of auto_verify_text. It slightly exceeds the baseline but the schema already does heavy lifting for src, verify_text, and auto_verify_text.

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

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

The description opens with a specific verb+resource: 'Describe what an image shows, as one detailed prose caption,' and immediately scopes it as 'the default choice for what is this a picture of,' noting it returns a single paragraph with no coordinates. It explicitly distinguishes itself from query_image (specific questions), dense_region_caption (caption+box per thing), and ocr (transcription), so an agent can disambiguate without opening sibling schemas.

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

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

It gives explicit when-to-use and when-not-to-use guidance, naming each alternative tool and the condition that selects it: 'Reach for a different tool when the question is narrower: query_image to ask something specific... dense_region_caption to get a separate caption and box for each thing... ocr to transcribe text rather than describe it.' It also gives conditional guidance for the boolean flags — set verify_text 'when a specific piece of text matters' — and states the PDF page-per-caption behavior. Nothing is left to inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers extensively. It discloses measured failure modes (heavy overlap undercounts: 8 shapes count as 6 when overlapping; the paper flower returns 1 at every resolution), explains the silhouette block and that count and silhouette.lobes come from different methods and neither overrides the other, describes the consensus and separable fields, and explains the generic-object-name guard. It also discloses that scores are unavailable on the clip_art path and that group_boxes_dropped is not applicable. This is far beyond what annotations would have provided.

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

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

The description is long but every section earns its place: it front-loads the core purpose and sibling differentiation, then layers behavioral caveats, output semantics, and parameter-specific guidance. The structure uses clear section breaks and bolded terms. It is not concise in word count, but it is dense with actionable information and well-organized. A 4 is appropriate because the length is justified by the tool's complexity, though it could be tightened in places (e.g., the paper-flower anecdote is illustrative but slightly verbose).

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

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

Given the tool's complexity (9 parameters, 2 required, no annotations, rich output schema), the description is remarkably complete. It covers when to use the tool, when not to, measured accuracy, failure modes, output field semantics, parameter effects, and even the generic-object-name guard. The output schema exists, so return values need not be fully re-explained, but the description goes beyond that to explain the meaning and reliability of the returned fields. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema. It explains the semantic distinction between count and silhouette.lobes, the meaning of separable values, the consensus fields, the estimates block, and the semantic_ambiguity/count_semantics fields. It also explains the generic-object-name guard and the clip_art path's lack of scores. The description enriches the output semantics far beyond what the input schema alone provides, and it clarifies how parameters like consensus, vqa_estimate, and verify_silhouette affect the output structure.

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: 'Count how many instances of a named object an image contains.' It immediately distinguishes itself from the sibling detect_objects by explaining that detect_objects returns regions, not a tally, and that count_objects is the tool to use when the question is 'how many'. This is a textbook example of purpose clarity with sibling 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 explicitly says 'Use this, not detect_objects, whenever the question is "how many"' and explains why detect_objects is unsuitable (it collapses repeated parts and splits objects). It also provides detailed when-to-use guidance for parameters like clip_art (flat vector art), threshold (cluttered scenes), consensus (independent second opinion), and vqa_estimate (when detector collapsed). It even gives measured examples of when the tool fails (heavy overlap, low-contrast petals) and advises checking query_image in those cases. This is comprehensive usage guidance with explicit alternatives and exclusions.

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

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

With no annotations, the description carries the full burden and is highly disclosive. It states that the VQA explanation only triggers below `low_score_threshold`, that auto-detection degrades on busy scenes, that a soft-failure shape is returned rather than raising, that only the first PDF page is assessed, and that relative mode does not recalibrate the absolute score.

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 long but densely structured, with each paragraph covering one distinct concern: core behavior, return shape, subject detection and PDF handling, style context, and relative mode. The core action and primary alternative are front-loaded, and there is no filler.

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

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

For a 5-parameter tool with multiple modes, the description covers inputs, return semantics, edge cases, and failure behavior. It clarifies ambiguous return fields like `thirds_offset`, `center_offset`, `delta`, `preferred`, and `cross_medium_warning`, so nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema. It explains that `target_subject` can come from a prior `caption` call, that `low_score_threshold` gates the Moondream2 explanation, that `style_context` adds `style`/`style_distribution`, and that `compare_with` switches the result shape and defines the tie threshold.

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

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

The description names a specific verb and resource ('Critique an image's composition') and details the constituent checks: framing, rule-of-thirds/centeredness on the subject bounding box, and a conditional Moondream2 explanation. It explicitly differentiates itself from the sibling `score_aesthetics`, so an agent can tell them apart without inspecting schemas.

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

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

It explicitly says when to use this tool over `score_aesthetics` ('when you need to know *why* a shot is weak and where its subject sits in the frame, rather than just how it scores'). It also gives parameter-level guidance: pass `target_subject` if known, set `style_context` for medium-aware scoring, and set `compare_with` for relative mode.

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 itself. It discloses the key behavior: the tool discovers salient regions autonomously and returns bboxes and labels for each. It does not discuss edge cases like images with no salient regions, but the core operational behavior is clearly stated.

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 tight and front-loaded: one sentence states the purpose, then a short paragraph explains when to use it and how it differs from alternatives. Every sentence contributes useful selection and invocation information without repeating schema contents.

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

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

Given a single well-documented parameter, an output schema, and a clear comparison to relevant siblings, the description provides everything needed to select and invoke the tool correctly. The mention of return contents (bboxes and labels) is useful despite the output schema existing.

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

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

There is only one parameter, src, and the schema already documents it thoroughly, including local paths, http(s) URLs, PDF rendering, and per-page list behavior. The description adds no extra parameter-level guidance, so the baseline of 3 applies because the schema coverage is complete.

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: 'Caption every salient region of an image at once, with bounding boxes.' It clearly differentiates this tool from siblings by explaining that detect_objects requires a named object and caption gives whole-scene prose without coordinates.

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

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

It gives an explicit use case: inventory an image without knowing in advance what is in it. It also names the alternatives and exactly what makes them different, so an agent can decide when to use this tool instead of detect_objects or caption.

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 behavioral burden, and it delivers: it discloses that the count is unreliable under ambiguous names (Florence-2 overlapping sub-part boxes, fused instances), that boxes cannot answer touch/inside questions, that a vague object_name yields a near-full-frame box that gets filtered out, and that neither tool separates heavily overlapping instances. This is rich, honest behavioral disclosure with zero annotation support.

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 long — four substantial paragraphs — but it is not padded. It is front-loaded with the core purpose and return format, then each subsequent paragraph addresses a distinct footgun (count unreliability, spatial limitations, generic vocabulary). The length is proportionate to the tool's genuine behavioral complexity, and every sentence earns its place. Slightly long for a first read, hence not a 5.

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

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

This is a complex tool with real failure modes, and an output schema exists to document return values. The description covers the return format, the return_annotated variant, count unreliability, sibling differentiation, spatial limitations, and the vague-name edge case. Nothing an agent needs to call it correctly is missing, given the rich schema and output schema that accompany it.

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

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

Schema description coverage is 100% and the schema already documents src, object_name, and return_annotated well, so the baseline is 3. The description adds genuine interpretational value: it explains how object_name specificity affects grounding reliability and the return_annotated key, and it teaches the agent how to interpret the returned bboxes/points/labels (index-aligned, centers come free). This bumps it above baseline without fully re-documenting 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 opens with a specific verb-resource pair: 'Locate a named object in an image, as bounding boxes and center points.' It states exactly what is produced (bboxes, points, labels) and is clearly differentiated from siblings: it tells the agent to use count_objects for tallies and spatial_relations for touch/containment questions, so detect_objects cannot be confused with either.

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

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

The description gives explicit routing guidance: 'Use count_objects when you actually need "how many"' and 'Use spatial_relations for that' for overlap/containment questions. It also advises preferring a more specific object_name and warns against generic vocabulary. The when-to-use and when-not-to-use guidance is unambiguous and names the exact alternatives.

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

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

With no annotations provided, the description fully carries the behavioral burden. It discloses that it uses EasyOCR, handles column layouts automatically, returns an empty result for no-text images rather than failing, and that detail=true exposes confidence scores and bounding boxes useful for detecting gibberish text. This is rich, non-obvious 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 long but well-organized and front-loaded with the core purpose. Each paragraph adds a distinct point: capabilities, routing, column handling, empty-result semantics, and detail guidance. It could be slightly tightened, but nothing is extraneous.

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

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

For an OCR tool with a rich schema and output schema, the description covers selection, alternatives, edge cases, and advanced usage. It explains what happens with no text, how columns are handled, and when to use detail. No critical information needed to invoke the tool correctly is missing.

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

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

The schema already describes both parameters at 100% coverage, so the baseline is 3. The description adds value beyond the schema by recommending detail=true for generative-artifact checking and explaining that low confidence indicates invented or gibberish text, which the schema does not convey.

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

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

The first sentence states a specific verb and resource: 'Process an image file or URL using OCR to extract text.' It further distinguishes itself from the sibling tool query_image by explaining that query_image paraphrases rather than transcribes, making the tool's unique role explicit.

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

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

The description explicitly says this is the right tool for 'any text in an image' and explains why query_image is not appropriate. It also gives when-to-use guidance for detail=true and warns against re-asking a captioning model when no text is found, covering both use and non-use cases.

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 and meets it: it warns that plain English 'does not fail' but returns confident nonsense, and that the output is raw text either way. This exposes the tool's raw-token-only nature and its key failure mode, which is exactly the context an agent needs.

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

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

Three short paragraphs, each earning its place: a scope sentence, a critical failure-mode warning, and routing guidance. The caveat about confident nonsense is essential rather than filler, and the most important constraints are front-loaded.

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

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

For a two-parameter escape-hatch tool, the description tells the agent what it does, what it does not do, when not to use it, what failure looks like, and what the return is. The schema covers parameter formats and PDF behavior, so nothing essential is missing.

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

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

The input schema already describes both src and prompt at 100% coverage, so the baseline is 3. The description reinforces the token-vs-instruction distinction and the garbage-output risk, but it does not add a significant new parameter-level fact beyond what the schema already says. No compensation is needed here, so 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 names a specific action ('Run a raw Florence-2 task token against an image'), identifies the tool as an escape hatch, and distinguishes it from the sibling wrappers by stating it applies only to tokens those tools do not already cover. This is far more informative than the generic tool name 'process'.

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 'Only for task tokens the named tools do not already cover' and instructs the agent to prefer caption, ocr, detect_objects, and dense_region_caption, explaining why those are better (they parse structured output and document misleading cases). The routing decision 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It discloses the model's documented failure modes (flat 'None' answers, same yes/no across different images), explains the confidence semantics, and describes the cross-check routing behavior including when it is omitted ('it never guesses'). This is exactly the kind of behavioral context an agent needs 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 long but every sentence earns its place: it covers purpose, sibling differentiation, failure modes, confidence semantics, and cross-check routing. It is front-loaded with the core purpose and the key alternative. It loses one point for density — the cross-check explanation is somewhat run-on and could be tightened — but it is not padded or redundant.

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

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

Given the tool's complexity (4 params, no annotations, rich behavioral nuances, output schema present), the description is complete. It explains the return types, the failure modes, the confidence field, the cross-check routing, and the structured_analysis bypass. An agent has everything needed to decide when to call it and how to interpret 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value beyond the schema by explaining the return-shape change when check_consistency=true (list[str] vs dict per image) and by detailing the cross-check routing logic that depends on the question wording. It also clarifies the src parameter's PDF behavior indirectly through the schema, but the description's main added value is on check_consistency semantics, which are already partially in the schema. The description does not add much beyond the schema for src or question, but the check_consistency elaboration justifies a 4.

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 ('Ask a free-form question about an image (visual question answering)') and immediately distinguishes itself from the ocr sibling by naming the exact use case (watermarks, logos, signage, stylized text). It clearly identifies what the tool does and what it is not for, so an agent can select it correctly without opening the schema.

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

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

The description explicitly says when to prefer this tool over ocr ('The ocr tool misreads that kind of text confidently; prefer this one for it instead'), and it gives concrete example questions. It also explains when to set check_consistency=true and when the cross-check routing applies, providing clear decision guidance for the agent.

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, and it delivers thoroughly. It discloses the CLIP-based model, the photographic training bias, version-dependent payload changes, the tie threshold of |delta| < 0.05, and the cross_medium_warning behavior. There is no contradiction with any annotation, and no surprising side effects are hidden.

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-structured and front-loaded with the core purpose, then moves through output, bias, and parameters. It is longer than necessary and repeats some parameter details that the schema already states, but every paragraph contributes a distinct piece of calibration or behavioral context.

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 three parameters, two optional modes, model-specific caveats, and version-dependent output, the description is complete. It covers the output shape, score scale, photography bias, fine-art caveat, comparison semantics, style classification, and version-specific payload enrichment. An agent selecting or invoking this tool has everything it needs.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds conceptual rationale beyond the schema: compare_with is framed as the calibrated like-with-like route around photography bias, and style_context is framed as the answer for non-photographic media. The added value is real but modest because the schema parameter descriptions are already unusually rich and largely overlap with the prose.

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-plus-resource statement: "Rate how aesthetically pleasing an image looks, independent of its content." It explicitly scopes out content correctness and prompt matching, which distinguishes it from content-focused siblings like caption or detect_objects. It also signals the output shape and the two optional modes, making the tool's identity 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 gives explicit when-to-use guidance: compare like with like, such as several shots of the same subject or successive edits of one image. It also gives explicit when-not-to-use guidance: do not read a single absolute score as a quality verdict, and do not expect meaningful ratings for fine art. This is stronger than a typical 4 because it actively steers the agent away from common misuses.

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 behavioral burden, and it does so richly: it states the tool locates and segments objects, does not render judgments, assumes one best-scoring match per name, and has a guard for maximally vague names. It even discloses the color-discrimination limitation observed with same-shaped objects, which is precisely the kind of behavioral nuance an agent needs.

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

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

The description is long but logically organized: purpose, interpretation guidance, use cases, assumptions, and caveats. It is not wasteful, though the red/blue/green circle example is more detailed than strictly necessary. Still, every section earns its place by preventing misinvocation.

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

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

For a two-parameter tool with a full output schema, the description is complete: it covers what the tool measures, what it deliberately does not decide, when to prefer alternatives, the one-instance assumption, and failure modes around vague names. The presence of an output schema means return-value details need not be restated here.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value for the objects parameter: it explains the one-instance assumption, gives naming guidance for multiple instances, and warns about vague names being dropped. It does not add anything specific to src, but the schema already fully describes 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 opens with a specific verb and resource: 'Measure how named objects in an image sit relative to one another.' It then enumerates concrete measurements (touch, pixel distance, containment, elongation) and explicitly positions this as geometry rather than verdicts. This distinguishes it from siblings like detect_objects and count_objects, which only locate or tally.

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

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

The description gives explicit when-to-use contexts: checking physical coherence, verifying placement, and answering contact/containment/clearance questions that bounding boxes cannot resolve. It also gives an explicit alternative for multiple instances ('use count_objects for a tally instead') and warns against vague object names, so an agent can route to the correct tool.

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