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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses offline operation, refusal to load data or images from URLs/files, a 50,000-row cap, and that PNG is rasterised from SVG at 'scale' (default 2×). These sandbox and size constraints are materially useful calling context the annotations don't carry.

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?

Front-loaded with the core action, then the two input modes, then constraints and the PNG scale detail. It's dense but every clause (refusals, row cap, field inference) earns its place for a 14-parameter tool; the semicolon-heavy single paragraph slightly hurts scanability.

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 14 params, nested 'spec', and no output schema, the description covers both invocation paths and limits well. It doesn't state the return value explicitly (file path vs. base64), which matters without an output schema, keeping it just short of 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 already 93%, so the baseline is 3, but the description adds genuine meaning: type inference rules (numbers = quantitative, ISO dates = temporal, else categories) and that y may be a list of fields for multi-series charts. This complements the schema rather than repeating 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?

States a specific verb and resource ('Render a chart to an SVG or PNG file, offline') and immediately enumerates the two supported input modes. An agent can tell this apart from sibling tools like ai_diagram or image_svg_to_png 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?

Explicitly frames the two mutually exclusive invocation paths (simple {type, data, x, y} vs. a full Vega-Lite/Vega 'spec') and notes field-type inference and what is refused. It stops short of naming a sibling alternative (e.g., ai_diagram for flowcharts), so it's clear context without exclusions across 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 cover safety (readOnly/idempotent/closed-world), and the description adds genuinely new behavior: heading-aware split order, never splitting inside code fences, mid-sentence cuts only when a sentence exceeds maxTokens, overlap only within the same section, and the caveat that Claude token counts are estimates. It also discloses the maxChunks inline cap vs. the JSONL file always containing all chunks.

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?

Well front-loaded: purpose first, then split strategy, then return fields, then input modes. It is dense (a single long paragraph covering splitting, overlap, return fields, tokenizer, and I/O modes), which slightly hurts scannability but every sentence carries information.

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

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

There is no output schema, yet the description enumerates each returned field (index, text, tokens, startChar/endChar, heading path) and the JSONL side-effect, plus the tokenizer caveat. An agent has everything needed to predict inputs and outputs.

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 baseline is 3; the description goes beyond it by explaining overlap semantics ('same section only'), that endChar is exclusive with CRLF normalisation to \n, the tiktoken default and Claude caveat, and the includeText default flip when output is given.

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

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

States a specific verb+resource ('Split text, markdown or a text file into token-sized chunks') with an explicit purpose (RAG/embeddings). An agent can immediately distinguish this from siblings like ai_token_count or ai_pdf_to_markdown.

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?

Clear usage context is given: 'Give "text" or "path" ... give "output" to also write the chunks as JSONL', which tells the agent how to invoke for the desired result. It does not name alternatives or exclusions (e.g., when to prefer ai_token_count or a markdown converter first), 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?

Goes well beyond the annotations by disclosing hard limits (300 slides), layout rules (text plus visual side by side), RTL handling for Arabic/Hebrew, table overflow onto extra slides, and cross-application compatibility. It does not mention that a file is written to disk and where, though the `output` parameter partly covers that; readOnlyHint=true is slightly at odds with file creation but the tool is non-destructive in spirit.

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?

Front-loaded with the action and artifact, then a dense but useful inventory of capabilities. The single long sentence is heavy but every clause carries information; only the compatibility sentence ('Opens in PowerPoint, Keynote...') is close to 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 an 8-parameter generator with no output schema, the description never says what the tool returns (a file path? a status object?) or how errors surface. Behavior and content modeling are well covered, but the return contract is left entirely to inference.

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

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

With 63% schema coverage, the description adds real meaning: bullets may be nested, chart types are native and editable, table first row is a header, images come from path or base64. It does not touch `theme`, `slideNumbers`, or `returnBase64` semantics, so it adds value without fully compensating for the schema gaps.

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

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

States a concrete verb and artifact ('Build a 16:9 PowerPoint (.pptx) deck') and immediately distinguishes itself from the sibling ai_pptx_to_markdown by being the generator rather than the extractor. The enumeration of slide content types (bullets, paragraph, image, table, chart, notes) makes the scope 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 says it works 'from a simple outline', which implies when it fits, but never names a precondition or an alternative (e.g. when to prefer ai_diagram, or converting markdown first). No when-not-to-use guidance is given, leaving the agent to infer routing.

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

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

The annotations declare readOnlyHint=true, but the description explicitly says the tool writes an .xlsx file to output and returns the path. That is a direct contradiction of the read-only annotation, so behavioral transparency is scored 1 despite otherwise rich behavioral detail.

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 front-loaded and dense with useful details rather than filler. It packs many capabilities into a single paragraph, though it could be more scannable with separate sentences or bullets for formulas, formatting, and limits.

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, the description covers the important call semantics: sheet structure, formatting defaults, formulas, date handling, limits, and return behavior. With no output schema, it usefully states that the result includes the path and a summary of each sheet.

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 high at 83%, so the schema already documents most parameters. The description still adds meaningful semantics beyond the schema, including the 50-sheet and 1,000,000-row limits, formula handling, date conversion behavior, and totals-row calculation behavior.

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: building a real Excel .xlsx file from data. It clearly distinguishes this creation tool from the conversion/read sibling ai_xlsx_to_markdown and from ai_create_pptx by naming the exact output format.

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

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

The description makes the tool's domain clear but never explicitly states when to use it versus alternatives or when not to use it. Usage is implied by the capabilities listed, such as creating workbooks with sheets, formulas, and totals, but no explicit routing 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?

Annotations already cover the read-only, closed-world, idempotent profile, so the description's contribution is the local-execution guarantee ('nothing is uploaded') and the missing-value convention (empty cells, 'null', 'NULL' count as missing), both of which an agent needs. It stops short of describing cost, limits, or failure behavior for malformed input.

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?

Front-loaded with the purpose, then the output inventory, then input modes, then a privacy note — a sensible ordering. The middle sentence is a dense parenthetical list of statistics and warning types, which is information-rich but reads as a run-on rather than structured bullets.

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?

There is no output schema, so the description carries the full burden of describing the return payload, and it does so exhaustively — counts, inferred types, per-type statistics, and warning categories. Combined with input-mode and missing-value semantics and annotation-covered safety, nothing an agent needs to decide or invoke 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 baseline is 3; the description adds value by explaining that 'file' accepts a local path or base64 across CSV/TSV/JSON/JSONL/XLSX, that 'sheet' applies to xlsx, and that 'csv'/'json' are inline alternatives. The only gap is that 'columns' and 'format' selection are not elaborated beyond the schema 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?

States a specific verb and resource ('Profile a table') and enumerates the exact artifacts produced: row/column counts, inferred per-column types, null/unique counts, top values, numeric stats, date ranges, and data-quality warnings. An agent can distinguish this from siblings like csv_to_json or ai_json_schema_infer without opening any 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?

Explicitly frames the use case ('to understand and clean it before analysis') and the data-quality warnings section implies adoption for cleaning workflows before transformation. It does not 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?

Annotations already declare readOnlyHint/idempotentHint, so the safety profile is covered; the description still adds substantial non-obvious behavior: top-3 candidate scoring semantics, the 20-character too-short threshold, dominant-script rule for mixed text, 100,000-character truncation, and the Hebrew exclusion. These are exactly the edge cases an agent would otherwise get wrong.

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?

Information-dense but front-loaded: core purpose and return format first, then caveats, then input contract. It is long-ish for one paragraph, yet nearly every clause carries a distinct constraint that is not restated elsewhere.

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?

There is no output schema, so the description carries the return-value burden and does so thoroughly (top-3 with scores, names, ISO 639-1, per-script shares). Combined with the degradation rules and input contract, an agent has everything needed to call it and 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 baseline is 3, but the description adds the one-of contract between 'text' and 'path' that the schema (0 required params, no oneOf) does not express, and clarifies the expected file type (UTF-8 text/markdown). 'only' is left to the schema, which documents it adequately.

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

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

States a specific verb+resource ('Detect the language of a text') and immediately names the engine and scope (franc-min, 82 languages, ISO 639-3) plus the secondary output (writing systems). It also spells out exactly what is returned, so an agent knows the tool's output shape from the description alone.

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?

Gives real operating guidance: best on a sentence or more of one language, mixed text falls back to the dominant script, and short inputs (<20 chars) degrade to script-only. It also states the input contract ('Give "text" or "path"'). No alternatives are named, but no sibling performs language detection, so there is nothing to route against.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses the layout engine, hard limits (500 nodes, 2000 edges), the label-measurement caveat (Helvetica/Arial metrics, Latin text best), and that the default destination is a server output folder. The only notable silence is what the tool actually returns (path vs inline content), which the readOnlyHint does not 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?

Purpose is front-loaded in the first clause, then the DSL grammar and limits follow in a single dense run-on. Every clause carries information, but the packed semicolon syntax makes it harder to scan than a short bulleted grammar would be.

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

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

With 8 parameters, a nested object schema and no output schema, the description covers both input modes, size limits, layout behaviour, and destination defaults. The gap is the return contract (file path vs base64 payload) and the interplay of 'output' with 'returnBase64', which the agent must infer.

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 already 88%, but the description adds real value by fully specifying the DSL accepted by 'source' (direction, title, node shapes, edge operators, quoting, comments, line breaks) and the JSON shape for 'graph'. It says nothing extra about theme, scale, or returnBase64 beyond their schema descriptions, so it stops just short of a 5.

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

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

States a specific verb and resource ('Draw a flowchart / graph diagram'), the output artifacts (SVG or PNG), and the layout engine (dagre). An agent can distinguish this from ai_chart (data charts) and image_svg_to_png (rasterising existing SVG) 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?

Usage context is implied through the input modes ('tiny text language ... Or pass JSON ... as "graph"') and the limits, but there is no explicit statement of when this tool should be chosen over siblings like ai_chart or image_svg_to_png, and no when-not guidance. The agent must infer suitability from the diagram/DSL framing.

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

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

Beyond the readOnly/idempotent annotations it discloses the practical traits that matter: images become placeholders unless embedImages is true (data: URIs, potentially very large), inline Markdown is truncated at maxChars while a written file is never cut, and nothing is uploaded. It also describes the return payload (warning count plus first few messages), which annotations cannot convey.

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

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

Purpose and format are front-loaded, then behavior details, then constraints; every sentence carries information. It is dense and packed into a few long sentences, which costs a bit of scannability but little is wasted.

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?

No output schema exists, yet the description covers return values, truncation caveats, image handling, file-vs-inline output, accepted input forms, and the unsupported .doc case. For a 4-parameter conversion tool that is everything an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real semantics by explaining the tradeoff behind embedImages (huge data: URIs) and the truncation behavior of maxChars, plus that a written output file escapes truncation. It slightly duplicates schema text ('default 200k') rather than adding further 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?

States a specific verb and resource ('Convert a Word .docx document to Markdown') and enumerates the constructs handled (headings, bold/italic, lists, links, tables, footnotes). The .docx source format cleanly separates it from ai_pdf_to_markdown, ai_html_to_markdown, and ai_markdown_to_docx (the reverse direction).

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?

Gives concrete applicable context: accepts a local path or base64, old binary .doc is explicitly excluded, and 'output' saves to a file instead of inline text. It does not name sibling converters as alternatives, so the routing is implied by format rather than stated.

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

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

Goes well past the readOnly/idempotent annotations: results are deduplicated with counts, card-like numbers are only returned when Luhn-valid with a known brand and are always masked to the last 4 digits ('the full number is never returned'), IBANs get country-length and mod-97 checks, and ambiguous 03/04/2024 dates are flagged with the alternate reading. That is exactly the kind of privacy and validity context annotations cannot convey.

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

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

Front-loaded with the core action and input options, and nearly every clause carries operational meaning. The long currency enumeration ('$, €, £, JOD/JD/د.أ, SAR/ر.س, AED/د.إ...') is the one place where detail could be compressed without losing agent-relevant information.

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

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

For a tool with no output schema, it does a good job describing the shape of results (per-type, deduplicated, counted, masked cards) and the date/phone normalization rules. It stops short of specifying the exact response envelope, so an agent still cannot predict the precise JSON structure.

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 explains what defaultRegion actually changes (local phone parsing plus D/M/Y vs M/D/Y disambiguation) and that outputs are deduplicated, but it largely restates the schema's own parameter descriptions rather than adding new semantics for 'types' or 'maxPerType'.

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?

Opens with a concrete verb and resource ('Pull structured items out of text or a text file') and then enumerates exactly which entity classes are recognized, so an agent knows precisely what comes back. The closing 'Regex-based, not NLP: no names, places or organisations' draws a sharp boundary that separates it from true NER/OCR-style siblings.

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

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

States the input contract plainly ('Give "text" or "path" (file path or base64)') and rules out a whole use case up front with 'no names, places or organisations'. It does not name an alternative sibling (e.g. ai_ocr for images, text_social_count for social stats), so the when-to-use-differently guidance is implied rather than explicit.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses the underlying library (file-type), the ~150-format coverage, that 'Nothing is executed', and the accepted input forms (path or base64). This is exactly the behavioral context annotations don't carry.

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?

Front-loads the core purpose and packs useful detail into a few dense sentences with no filler. Slightly long due to the return-value enumeration, but each clause carries information.

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

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

With no output schema, the description fully compensates by enumerating the returned fields (detected type, MIME, mismatch flag, size, SHA-256, encoding and text-kind guess). An agent knows exactly what calling it yields.

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 both parameters are already documented. The description reinforces that a path or base64 is accepted and that the extension comparison happens, but adds little syntax or format detail beyond the schema; 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?

Starts with a specific verb and resource ('Find out what a file really is from its content'), scopes it to magic-byte detection across ~150 formats, and explicitly contrasts it with name-based guessing. An agent can distinguish this from siblings like ai_media_info or hash_compute without opening a 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 'from its content, not its name' framing implies when this is the right tool versus name-based inference, but it never names an alternative (e.g., ai_media_info) or states when NOT to use it. Usage is implied rather than spelled out.

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

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

Annotations already mark this as read-only, idempotent, and not open-world, but the description adds important behavior beyond them: scripts/styles/forms are removed, 'readable' falls back to the whole body, inline output is truncated at maxChars with a note, file output is never cut, and processing runs locally with nothing uploaded.

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 one dense but well-structured paragraph that front-loads the purpose, then covers input modes, transformation options, truncation behavior, and privacy. Every sentence serves the caller; no filler is present.

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

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

For an 8-parameter conversion tool with no output schema, the description is complete enough: it explains input sources, output-file versus inline behavior, truncation, content filtering, link handling, and local execution. An agent has what it needs 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 eight parameters in detail. The description mostly restates those parameter meanings and adds only marginal semantics such as the Readability fallback; therefore the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: convert HTML to clean Markdown, with concrete output elements such as headings, lists, links, tables, and code blocks. It is immediately distinguishable from sibling conversion tools like ai_pdf_to_markdown and ai_docx_to_markdown by source format.

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

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

It gives clear usage context ('for reading or feeding to a model') and explains input modes (inline 'html' vs 'path'), plus when to use options like 'readable' and 'selector'. It does not explicitly compare against sibling conversion tools or state when not to use this tool, 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?

On its own the description is unusually transparent: it discloses that a diff PNG is written with red-diff over a faded reference, that pixel count and percentage are returned, and that inputs must match in size unless resize is true. But it explicitly describes a filesystem write while annotations declare readOnlyHint=true and idempotentHint=true, which is a material inconsistency for an agent deciding whether this call has 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?

One dense paragraph with essentially no waste and the core operation front-loaded; format and size limits follow in a logical order. Slightly run-on, packing formats, size limits and use case into a stream rather than separated cues.

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 no output schema, the description correctly carries the return info (different-pixel count and percentage) and the artifact produced (diff PNG). A couple of details an agent might want are absent, such as the returned path of the diff file and error behavior when sizes mismatch, but nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics beyond the schema: it explains that resize stretches the second image to the first's size, that anti-aliasing awareness is default behavior unless includeAA, and that inputs may be paths or base64 within a 50 MP cap. It does not cover threshold or output/returnBase64 behavior, so not a 5.

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

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

States a specific verb and resource ('Compare two images pixel by pixel') and immediately names the underlying algorithm and output artifact (pixelmatch diff PNG). It is unambiguously distinct from siblings like text_diff, image_convert or image_resize.

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 closing sentence 'Good for visual regression checks' gives a concrete use case, and the size/resize constraint tells the agent when it can and cannot be called. It stops short of naming an alternative tool for non-visual comparisons, so a 4 rather than 5.

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

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

The annotations declare readOnlyHint=true, but the description says the tool can optionally write the schema to an output file. Writing a file is a side effect, directly contradicting the readOnlyHint annotation.

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

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

The definition is dense but front-loaded, starting with the core generation behavior and then covering inference rules. It earns most of its length, though it could be more clearly structured for an 11-parameter tool.

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 input modes, inference behavior, and optional output for a complex tool with no output schema. It is nearly complete, but it does not explicitly state the exact return shape and includes the readOnly contradiction.

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 every parameter is already documented in the input schema. The description adds useful behavioral context around sample interpretation and eachItem, but most of the parameter semantics are already present in the schema.

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

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

The description states a specific verb and resource: generate a JSON Schema from sample JSON values. It is clearly distinguishable from the sibling ai_json_schema_validate, which would validate rather than infer a 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?

Usage is implied by the purpose: supply sample JSON and receive an inferred schema. However, the description never explicitly says when to choose this over ai_json_schema_validate or what inputs are unsuitable.

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 cover the safety profile (readOnly, idempotent, openWorld=false), yet the description still adds substantial behavioral detail: allErrors reporting with instancePath/schemaPath/keyword/message/params, draft resolution rules ($schema-driven 2020-12/2019-09, else draft-07, with 04/06 coerced), which formats are actually checked versus ignored and listed, and that remote $ref URLs are never fetched because it runs locally.

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?

Front-loaded with purpose, then error reporting, then draft handling, then formats, then input plumbing, then the no-remote-fetch guarantee. Dense but every clause carries non-obvious information; no filler or restatement of the title.

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

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

With no output schema, the description takes responsibility for describing the return payload (per-error fields) and caps behavior via maxErrors context. Draft support, format coverage, and the no-network guarantee fill in the remaining gaps an agent would otherwise have to guess at.

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 already 100%, so baseline would be 3; the description earns above that by grouping the six parameters into data sources and schema sources and clarifying the edge case that an inline string in 'data' is validated as a string rather than parsed. maxErrors is left to the schema, which is acceptable given its explicit description.

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?

Opens with a specific verb+resource: 'Validate JSON data against a JSON Schema with Ajv', then narrows to what is reported. This is unambiguously distinct from the sibling ai_json_schema_infer (which produces schemas rather than checking data) even without naming it.

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

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

Gives explicit selection guidance among the alternative input modes — inline 'data' vs 'dataText' vs 'dataFile', and 'schema' vs 'schemaFile' — with the crucial caveat that a string passed as 'data' is validated as a string. It stops short of stating when to prefer this tool over sibling tools such as json_format or ai_json_schema_infer.

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

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

The description is unusually rich about behavior — RTL auto-detection, default Calibri, default output name derived from the title/first heading, HTML dropped, images not embedded — far beyond what the annotations state. However, it explicitly says 'Writes the .docx to "output"', which conflicts with the declared readOnlyHint=true; an agent trusting the annotation could be misled about filesystem side effects. The description itself is not misleading, but the conflict with structured metadata caps this dimension.

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 core operation and scope are front-loaded in the first clause, followed by a dense but scannable feature inventory. It is long, and the feature list could be compressed, but essentially every clause carries information an agent cannot get from the schema.

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

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

With zero required parameters and no output schema, the description does the important work: it tells the agent that one of markdown/path must be supplied and explains where the file lands. It does not describe the tool's response payload (beyond the returnBase64 option), which is the main remaining gap.

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

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

Schema description coverage is 100%, so every one of the nine parameters is already documented; the description only restates a few (title/author as document properties, font default Calibri, fontSize, rtl "auto"). It adds the useful default-file-name rule tied to title/first heading, but returnBase64 and the output path semantics are left entirely to 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?

Opens with a precise verb+resource+output ('Convert Markdown (GitHub flavoured) to a real Word .docx') and enumerates the exact constructs handled. It is trivially distinguishable from siblings such as ai_markdown_to_pdf and ai_docx_to_markdown, which go the other direction or to another format.

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 states the two accepted input modes ('Give "markdown" inline or "path" to a .md file') and the two non-conversions (images not embedded, raw HTML dropped), which lets an agent judge fitness. It never explicitly names when to prefer ai_markdown_to_pdf or ai_docx_to_markdown, so it stops short of full routing guidance.

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

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

The annotations declare readOnlyHint=true, but the description says the tool writes a result: the "output" parameter accepts "a file path, or a folder ending in '/'", with a default server output folder. Writing a PDF file modifies the environment, directly contradicting readOnlyHint=true. The rich feature and limitation disclosure otherwise adds useful context, but the annotation contradiction is serious.

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 dense and largely a single long feature list, but it is front-loaded with purpose and every clause describes relevant supported behavior or a limitation. For a 13-parameter conversion tool with no output schema, the length is defensible, though the run-on structure reduces readability.

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

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

The description thoroughly covers input Markdown features and limitations, but with no output schema it does not clearly state what the tool returns by default beyond the optional base64 behavior. It also leaves the write-to-file behavior in tension with the readOnlyHint annotation, so an agent lacks a fully coherent behavioral picture.

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 high at 77%, so the schema already documents most parameters. The description adds marginal clarity by saying "Give 'markdown' inline or 'path' to a .md file" and by explaining unsupported-character behavior, but it largely repeats parameter meaning already present in the schema.

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

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

The description states a specific verb and resource: "Turn Markdown (GitHub-flavoured) into a clean, paginated A4/Letter/A5 PDF." It clearly identifies the output format and supported Markdown features, but it does not explicitly differentiate from sibling tools such as ai_markdown_to_docx or other PDF utilities.

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 implied usage by stating "Give 'markdown' inline or 'path' to a .md file" and lists important content limitations such as Latin-only text and remote images never being fetched. However, it does not say when to use this tool versus alternatives like ai_markdown_to_docx or other PDF tools, and it provides no explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety is covered; the description adds genuine extra context: processing is offline, files are streamed so arbitrarily large inputs are fine, and VBR MP3s without a header require a full file scan (a real performance cost an agent should anticipate). That is exactly the kind of beyond-schema behavioral disclosure that earns a top 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 purpose lead is front-loaded and the field/format enumerations are dense but each list item carries routing value. The final VBR sentence is a useful edge-case note. It is long for a one-parameter tool but not padded with 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?

With no output schema, the description effectively enumerates the returned metadata fields (including per-track video dimensions), so an agent knows what it will get. Combined with 100% schema coverage and full annotation coverage, nothing needed 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 coverage is 100% and the single parameter's description already documents absolute paths, paths relative to --root, and raw or data: URI base64. The description reinforces this ('File path (streamed, any size) or base64') and adds the streaming/any-size caveat, giving modest value beyond the schema rather than repeating it outright.

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

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

States a specific verb and resource ('Read audio and video file metadata offline') and immediately enumerates the exact fields returned (container, codec, duration, bitrate, tags, cover art), which makes it unmistakable next to siblings like pdf_metadata_read, image_exif_read, or ai_file_identify. The explicit format list further removes any ambiguity about 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?

Usage is only implied: the description notes the offline nature and the accepted input forms (path or base64), which tells an agent this is the right tool when an audio/video container is involved. However, it never states when NOT to use it or names an alternative (e.g., use pdf_metadata_read for PDFs, image_exif_read for images), so routing is left to inference from the format list.

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

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

Annotations already establish readOnly/idempotent/closed-world, but the description adds substantial context beyond them: fully offline operation with bundled eng/ara models, nothing downloaded or uploaded, PDF pages rendered at 200 dpi by default, and the fact that "output" writes a side-effect .txt file while inline text can be truncated by maxChars. It also discloses performance and accuracy characteristics, which annotations cannot convey.

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

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

Everything is front-loaded — capability, formats, then languages/dpi/returns, then limits and the sibling alternative — and almost every clause carries information. It is a dense single block rather than scannable sentences, which slightly hurts readability for an agent parsing quickly.

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

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

For an 8-parameter tool with no output schema, the description still covers the return shape (text per page plus mean word confidence 0-100), the file-writing side effect, resource limits, and the closest alternative. 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 baseline would be 3; the description still adds value by restating the language set and default ("eng", "ara", "eng+ara"), the 200 dpi render default, and by clarifying that "file" accepts either a local path or base64 and that "output" writes a .txt file. The psm, pages, perPage, and maxChars parameters are left entirely to the schema, which keeps it just short of a 5.

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

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

States a specific verb (read/extract text) and resource (image or scanned PDF) and names the engine (Tesseract/tesseract.js). It also enumerates supported formats and explicitly distinguishes itself from the pdf_to_text sibling, so an agent can route 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?

Gives an explicit alternative and the condition that selects it: "For PDFs that already have a text layer, pdf_to_text is faster and exact." It also frames suitability (printed text works well, handwriting and small/skewed text poorly) and hard limits (200 pages, ~1-5 s/page), which is exactly the when-to-use/when-not guidance an agent needs.

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

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

The description says the optional `output` parameter saves Markdown to a file, which is a write to the environment. This contradicts the annotation readOnlyHint=true, so the description and structured metadata conflict. Otherwise the behavioral detail about truncation, page markers, and empty pages is rich, but the contradiction takes precedence.

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

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

The description is front-loaded and dense with useful specifics rather than filler. It is somewhat long for a single paragraph and includes minor repetition of schema details, but the length is justified by the tool's behavioral 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 tool with no output schema and six parameters, the description covers the key return behavior (inline Markdown or file path), truncation via maxChars, page filtering, page markers, and the scanned-PDF edge case including the pagesWithoutText signal. An agent has enough context 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 coverage is 100%, so every parameter is already documented in the schema. The description reinforces page ranges, page markers, maxChars truncation, and output-file behavior, but adds little semantic detail beyond the schema descriptions.

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

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

The description states a specific verb and resource (convert a text PDF to structured Markdown) and immediately characterizes the output structure. It clearly distinguishes the tool from OCR by explaining that scanned PDFs without a text layer produce empty pages and should be OCR'd first.

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

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

It gives clear usage context for text PDFs and explicitly redirects scanned PDFs to OCR first. It does not explicitly compare against sibling conversion tools such as pdf_to_text, so it falls short of full alternative routing.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds genuinely new context: it runs locally and uploads nothing, extraction silently drops images/charts/SmartArt, and inline Markdown is truncated at maxChars while an output file is never cut. These are the exact surprises an agent would otherwise hit at runtime.

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?

Front-loaded with the primary action and output format, then progressively narrows to exclusions, parameter hints, and the local-processing note. Every clause carries distinct information with no restatement of the name or title.

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

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

With no output schema, the description takes on the burden of describing the return value and does so concretely: slide headings, paragraphs, bullet indent levels, Markdown tables, and quoted speaker notes. Combined with exclusion and truncation notes, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description still adds value by showing a concrete slides range ("1-5, 8"), restating the 200k maxChars default with the truncation consequence, and clarifying that "output" returns a path instead of 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 opening clause names a specific verb and resource ("Extract the text of a PowerPoint .pptx deck as Markdown") and immediately defines the output shape ("## Slide N: title" per slide). This cleanly distinguishes it from sibling converters like ai_docx_to_markdown, ai_pdf_to_markdown, and ai_xlsx_to_markdown by source format.

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 sets clear boundaries on what it handles: "Old binary .ppt is not supported" and images/charts/SmartArt are excluded. It doesn't explicitly name an alternative tool for those cases (e.g. ai_pdf_to_markdown for exported PDFs), so it stops short of full when/when-not routing.

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

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

Beyond the annotations, it discloses allowed SQL features, refused SQL operations, CSV typing behavior, case sensitivity, quoting rules, inline result limits, output-file behavior, and that processing is local. This gives the agent substantial behavioral context for safe invocation.

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 dense but front-loaded with the core operation and then organized into dialect, table formats, restrictions, naming, and return behavior. It is appropriately sized for a complex tool, though the long parenthetical style is packed.

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 complex querying behavior, no output schema, and many input formats, the description is complete enough: it explains return values, row limits, output options, table input forms, and key restrictions. An agent can call it correctly without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful semantics: table names are case-sensitive, odd column names should be bracketed, CSV cells are typed, ISO dates remain sortable/comparable, and output saves every row. These details supplement the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Run one read-only SQL SELECT ... over one or more tables.' It clearly defines scope and dialect, though it does not explicitly name sibling alternatives such as json_query or csv_to_json.

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

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

It gives clear usage context, including the read-only SELECT restriction and a detailed list of refused statements and operators. It does not explicitly compare against alternative tools, so it stops short of full when-to-use/when-not guidance.

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

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

Annotations only cover read-only/idempotent/local, but the description adds real behavioral detail: normalization rules (lowercased, punctuation and Arabic diacritics ignored), the fact that dedupe groups are connected components (A~B, B~C merge), the 1000-text cap, and the metric-selection effect on both sorting and grouping.

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?

Front-loads the purpose, then algorithms, then semantics caveat, then mode/input mechanics. Dense but every sentence carries a distinct fact; no restatement of the title or name.

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 9 params, no required fields, and no output schema, the description still tells the agent what each pair returns and how results are ordered/grouped. An agent can pick a mode, choose a metric, and set a threshold correctly without further probing.

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 baseline is 3; the description goes further by tying 'threshold' to connected grouping semantics, noting shingle size k=3 as words per shingle, and clarifying that 'texts' and 'paths' can be combined. It does not explain 'labels' ordering or 'numHashes' accuracy tradeoff (that lives in the schema), so short of a 5.

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

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

States a specific verb and resource ('Compare two or more texts for overlap') and immediately enumerates the three returned measures. The caveat 'Measures wording overlap, not meaning (no embeddings): paraphrases score low' distinguishes it from semantic/diff siblings without naming them.

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

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

Explicitly explains the two modes and when each applies ('pairs' default lists sorted pairs; 'dedupe' groups near-duplicates at or above threshold), plus how to supply input via 'texts' and/or 'paths'. It never names a competing sibling (e.g. text_diff) or says when not to use it, so no full 5.

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

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

Annotations already establish that the tool is read-only, local, and idempotent. The description adds important behavior beyond that: no API calls, multi-second latency for large texts, approximate Claude token counts with a typical error range, and additional outputs such as characters, words, and context-window fit.

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

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

The description is front-loaded with the core purpose and then layers on encoding choice, Claude estimation caveats, local execution, input form, and large-text latency. Despite being dense, every sentence contributes operational information.

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

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

With no output schema, the description still explains the return values: token count, characters, words, and context-window fit. It also covers estimation caveats for Claude and performance for large inputs, leaving little an agent needs to know before calling it.

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

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

Schema coverage is already 100%, but the description adds useful clarifications: text and path are alternatives, path may be a local path or base64, and encoding maps to specific model families with a default. It mostly reinforces the schema rather than introducing extensive new parameter semantics.

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: count LLM tokens in text or a text file, and names the tokenizer families used. It is clearly distinct from adjacent utilities such as text_word_count because it emphasizes LLM token counting, encoding choice, and context-window fit.

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

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

It gives clear usage context: provide text or a path, choose o200k_base for GPT-4o/o-series and cl100k_base for GPT-4/3.5, and expect an estimate for Claude. It does not explicitly name alternatives or say when not to use this tool, so it falls short of the highest usage-guidance tier.

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?

Goes well beyond the readOnly/openWorld/idempotent annotations with concrete operational limits: 5 MB and 20 second caps, up to 5 redirects, SSRF protection on private/local/loopback addresses, robots.txt enforcement for the named user agent, and Readability-with-fallback behavior. It also discloses the key failure mode (JS-built pages yield near-empty output) and the truncation semantics of maxChars.

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?

Front-loaded with purpose and output shape, then a dense but purposeful run of constraints — every clause carries an operational fact. It is a single long paragraph rather than a scannable structure, which costs a point, but 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 7-parameter open-world fetch tool with no output schema, the description covers return shape (title, byline, final URL, word count, inline Markdown), truncation, redirects, timeouts, size limits, and safety refusals. An agent has everything needed to call it correctly and anticipate failures.

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 every parameter is already documented in the schema, including defaults for maxChars, readable, and allowPrivate. The description reinforces selector, maxChars, output, and allowPrivate but adds no syntax or format detail beyond what the schema states; 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 first clause names a specific verb and resource — fetch a web page over http/https and return its readable content as Markdown — and enumerates the returned fields. It is clearly distinguishable from file-oriented siblings like ai_html_to_markdown, which operate on HTML you already have rather than fetching a live URL.

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

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

It gives explicit operating conditions and exclusions: no JavaScript execution so browser-rendered pages may come back empty, robots.txt refusals, non-HTML responses rejected, and allowPrivate needed for localhost. It doesn't name a sibling tool to use instead when a page is JS-rendered, so an agent gets clear context but no explicit alternative.

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

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

Annotations already declare readOnly/openWorld=false/idempotent, and the description still adds substantial behavior: header taken from first used row, empty rows/columns trimmed, formulas show cached results, ISO dates, merged cells collapsed, hyperlinks converted. It also discloses truncation semantics (maxRows with a count of omitted rows, maxChars note) and that file output is never cut — details not derivable from the schema or annotations.

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

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

Front-loaded with the core conversion and the sheet-section output shape, then behavior details in a compact run-on list. Dense but nearly every clause carries distinct information; the only mild padding is the pair of example date formats.

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 six parameters, no output schema, and multiple accepted input forms, the description covers what the return looks like ('## sheet' sections, inline Markdown vs written file path), how truncation is signaled, and format detection — enough for an agent to call it correctly first try.

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 baseline is 3; the description earns above that by explaining the maxRows default of 200 and how truncated rows are reported, plus that an 'output' file is never truncated by maxChars — an interaction between two params the schema does not spell out.

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

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

States a specific verb and resource: turn an .xlsx/.csv/.tsv file into Markdown tables, one '## sheet' section per sheet. That immediately separates it from the other converters (ai_pdf_to_markdown, ai_docx_to_markdown, ai_pptx_to_markdown, csv_to_json) without the agent needing to compare 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 useful boundaries (old binary .xls not supported, local path or base64, sheet selection) but never says when to pick this over siblings like ai_csv_profile or csv_to_json, nor any prerequisites. Usage is inferable from the format constraint rather than explicitly stated.

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

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

With annotations only flagging readOnly=false, openWorld=false, idempotent=false, the description supplies the meaningful behavior: symlinks skipped, folder names preserved as top-level folder, zip-slip refusals for '..'/absolute paths/drive letters, existing files kept unless overwrite=true, and no support for encrypted ZIPs. It also states hard limits (500 MB, 10000 entries) that the annotations cannot express.

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?

Front-loaded with the action taxonomy, then limits, then unsupported cases – a sensible order with no filler sentences. Density is high because of parenthetical clauses, but every clause (symlink skipping, zip-slip refusal, default caps) conveys non-obvious behavior.

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

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

For an 8-parameter, multi-mode tool with no output schema, the description still covers each mode's inputs, default destinations, safety behavior, hard caps and an unsupported case. The 'list' mode's return shape ('entry names with sizes') is described, so nothing essential an agent needs before calling 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 88%, so the baseline is 3; the description earns above that by adding meaning the schema does not, notably that create paths are local paths whose folders keep their own name, that multi-part sizes are capped by maxTotalMB/maxFiles, and that extract's output defaults to the server output folder. It does not restate the level or overwrite semantics beyond what the schema already documents.

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

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

Opens with a specific verb+resource ('Work with ZIP archives locally') and then enumerates the three actions with concrete effects (zip, unpack, entry names with sizes). No sibling tool in the list touches archives, and the action breakdown makes the 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?

Each action carries an in-line statement of what it does and its constraints, which implicitly routes the agent between create/extract/list ('list: entry names with sizes, no extraction'). It does not name exclusions or prerequisites (e.g. when a caller should prefer a non-local upload path, or required filesystem access), so it falls short of explicitly stating when-not to use it.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, yet the description says the tool will 'write one file per value into a folder' and lets the caller pick an 'output' path — a filesystem side effect that readOnlyHint denies. Beyond that mismatch the description is genuinely informative (check-digit handling, invalid values non-fatal, subset C packing, system monospace font for PNG text), but the write-vs-readOnly conflict is a real inconsistency.

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

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

A single dense paragraph that is front-loaded with the output medium and symbologies, then moves to encoding rules and the value/values modes. Every clause carries information, though the run-on structure with semicolons makes it slightly harder to scan than it could be.

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

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

For a 13-parameter tool with no output schema and no annotations covering return shape, the description covers output destination (file path vs folder), the default temp output folder, and the optional base64 return. It does not explain the result payload (does it return written paths?), file naming for the "values" mode, or overwrite behavior — gaps an agent would care about for a batch-writing tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: EAN-13 accepts 12 digits and appends the check digit or 13 and verifies it, UPC-A works the same way, Code 128 takes printable ASCII with automatic subset C packing, Code 39 has a fixed charset plus optional mod-43, and value/values are alternative modes. Only the presentation parameters (scale, barWidth, height, colors) are left entirely to 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?

Opens with a specific verb+resource ('Make 1D barcodes as SVG or PNG') and then enumerates the four supported symbologies, immediately distinguishing it from qr_generate and the image_* siblings. An agent can tell exactly what this produces 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?

Explicitly states the two operating modes: supply "value" for a single barcode, or "values" (up to 1000) to write one file per value into a folder, plus the note that invalid values are reported rather than fatal. It stops short of naming a sibling alternative (e.g. qr_generate) or stating when-not to use it, so it does not reach 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?

Goes well past the annotations by disclosing the real side effect: binary results are written to disk with a detected extension, with a default temp output folder. Worth noting the mild tension with readOnlyHint=true, since file creation is a side effect, but the description discloses it rather than hiding it, so no real contradiction. It omits error behavior for invalid input.

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?

Front-loaded with the decode scope, then the all-important output-destination rule, so the reader gets the decision-relevant facts first. The second sentence is long because of the detected-type list, which is justified but slightly bloats the entry.

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 no output schema, the description carries the return-value burden and does so: inline UTF-8 text versus a written file whose extension reveals the detected type. Only gap is failure behavior on malformed Base64 and whether existing files at the target path are overwritten.

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 all three parameters are already documented, and the description's default-folder and extension-detection notes largely mirror the schema's "output" and "fileName" text. Baseline 3 applies; the description adds behavior around the parameters rather than new meaning within them.

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?

Specific verb+resource ("Decode Base64") with the scope of variants spelled out: standard or URL-safe, optional padding, whitespace and data: URI prefix accepted. An agent can distinguish this from base64_encode and image_from_base64 without opening a schema.

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

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

The description gives clear operating context: text decodes inline, binary (or anything with an explicit "output") goes to a file. It does not name alternatives, and the nearest overlapping sibling, image_from_base64, is never mentioned, so an agent must infer which one to pick when the payload is an image.

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

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

The annotations declare readOnlyHint=true, but the description states that results over 1 MB or when "output" is given are written to a text file. Writing files is a mutating side effect and directly contradicts the read-only annotation.

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

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

The description is compact, front-loaded, and covers the main behavior in one dense paragraph. The external web-version link is not essential for invocation and slightly weakens 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?

With no output schema, the description usefully explains that output is returned inline or written to a file, including the 1 MB threshold. It does not clarify precedence if both text and file are supplied, which is a minor completeness 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%, so parameters are already documented, but the description adds useful semantics beyond the schema: the 1 MB inline/file-output threshold and MIME type detection from magic bytes for data URIs. Some option descriptions merely restate schema text, so it stops short of 5.

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 gives a specific verb and resource: encode text (UTF-8) or a file to Base64. It clearly distinguishes the operation from the sibling base64_decode and from image-only base64 helpers by naming text and file-path inputs.

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

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

It explains when the option flags apply: URL-safe alphabet, MIME wrapping, data URI output, and file output. It does not explicitly compare against alternatives such as base64_decode or image_to_base64, but the usage context is clear.

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

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

Annotations already cover read-only, idempotent, and closed-world behavior, so the description adds useful context about input auto-detection, ignored separators, negative handling, and the additional bit-length/two's-complement output. It does not discuss error behavior for malformed inputs, but the added behavioral detail is substantial.

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

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

The main purpose and key constraints are front-loaded in one dense paragraph. It is appropriately sized for the tool's complexity, though the run-on structure and the website URL are slightly less essential than the core behavior.

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

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

With no output schema, the description does a good job summarizing the return surface: primary base conversions plus bit length and two's-complement details at 8/16/32/64 bits. It could be more explicit about the exact output shape, but it is complete enough for an agent to call 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 that values are arbitrary-size BigInts and reiterates prefix/separator handling, but most parameter meaning is already documented in the schema.

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

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

The description states a specific verb and resource: convert a whole number of any size between bases 2–36. It includes scope detail (BigInt, binary/octal/decimal/hex/base 36) and the extra two's-complement view, so an agent can distinguish it from unrelated calculator or byte-conversion siblings.

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

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

It gives clear context for use: whole numbers only, auto-detection from 0x/0b/0o prefixes, ignored separators, and negatives allowed. It also explicitly excludes fractions, though it does not name a sibling alternative such as calc_fraction, so it falls short of full when/when-not/alternatives guidance.

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

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

Annotations already establish readOnly, idempotent, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context the annotations cannot: lenient byte parsing and the fact that invalid UTF-8 is reported with U+FFFD replacements rather than erroring, which directly affects how an agent interprets results.

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 tight sentences: purpose first, then the lenient-input caveat, then the edge-case behavior, with the reference URL last. Every sentence carries information an agent could act on, and nothing is padded.

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 no output schema, the description carries return-value disclosure and does so partially: it says invalid UTF-8 is shown with replacements but does not state the overall return shape (e.g., that a string is returned in the chosen format). For a simple two-way conversion tool this is close to 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 goes beyond the schema by giving concrete accepted byte-input examples ('48 65', '0x48,0x69', '01001000 01101001'), clarifying that the bytes parameter tolerates mixed notation — semantics the schema does not convey. The uppercase parameter is only covered by the schema, keeping it just below 5.

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

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

States a specific verb and resource ('turn text into its UTF-8 bytes ... or bytes back into text') and enumerates the supported output formats. An agent can distinguish it from siblings like base64_encode/decode or base_convert because the description is explicitly about UTF-8 byte representation in hex/bin/dec.

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 bidirectional framing ('or bytes back into text') makes the two usage paths clear, and the lenient-input sentence tells the agent this tool accepts many byte input shapes. It does not, however, name when to prefer base64_encode or hash_compute over this tool, so the sibling routing is left 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?

Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is covered. Beyond that, the description discloses a genuine edge case ('Feb 29 birthdays fall on Feb 28 in common years'), the Hijri calendar convention (Umm al-Qura), the accepted date format, and the default display name for the second person. It stops short of saying what happens with invalid or future dates.

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 purpose is front-loaded in the opening clause and the rest is a dense but informative feature inventory. The single sentence is long and list-heavy, but since there is no output schema, most of the enumeration earns its place; a short break after the primary purpose would help.

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 four parameters, no output schema, and no nested structures, the description does the heavy lifting by telling the caller what the result contains as well as what it takes to call it. Only error behavior for malformed or impossible dates is left unaddressed.

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

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

Schema description coverage is 100%, so the baseline applies. The description adds only light context beyond the schema, restating the ISO YYYY-MM-DD format and that the second person is optional; the onDate 'today' default and otherName's 'They' default are already in the schema.

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

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

The description gives a specific verb and resource ('Exact age in years, months and days from a date of birth') and then precisely enumerates the scope: totals, weekday, Hijri date and age, next birthday, star sign, Chinese zodiac, 1,000-day milestone, and optional second-person gap. That is far more specific than a generic 'compute' statement. It never names the overlapping siblings calc_date_diff or calc_hijri, so the caller must infer the boundary itself.

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 is implied by 'from a date of birth' and by the schema default that onDate falls back to today, plus the note that the age gap to a second person is optional. There is no explicit when-to-use/when-not guidance and no pointer to alternatives such as calc_date_diff for day counts or calc_hijri for pure Hijri conversion.

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

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

Annotations already declare readOnly/idempotent/closed-world, so the safety profile is covered; the description adds real value on top with validity bounds (height 50–272 cm, weight 10–650 kg, age 18–120 for BMR), conditional behavior (BMR only when age is supplied and is adult), and a liability caveat. No return envelope detail, but the computed outputs are enumerated, so nothing important is 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?

Dense and front-loaded: capability list first, then unit systems, then validity bounds, then disclaimers — a sensible order. It is long for an MCP description, though nearly every clause carries information an agent cannot get from the schema or annotations.

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 8-parameter all-optional tool with no output schema, the description covers outputs, units, ranges, and the adult-only restriction well. The one real gap is that required-for-success inputs (weight plus a height in the matching unit) and the behavior when heightCm is given under imperial units are never stated.

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 the unit-system contract (metric cm/kg vs imperial ft+in/lb) and the numeric domain limits that the schema lacks. It does not explicitly restate which of the 8 optional parameters are actually needed for a valid call (height + weight), leaving that to inference.

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?

Opens with a specific resource and immediately enumerates the concrete outputs (WHO category, healthy weight range, BMI Prime, waist-to-height ratio, BMR, maintenance/loss calories), so an agent knows exactly what it gets back. It is clearly distinguished from the surrounding calc_* family (calc_age, calc_unit_convert, calc_stats) which do not compute body metrics.

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?

Gives explicit conditions: adults 18–120 with age get BMR/calories, children need percentile charts instead (a clear when-not), and there's a 'not medical advice' scope caveat. It also states the supported input ranges. It stops short of naming a sibling alternative, but no sibling actually overlaps this function.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds real substance beyond that: exact integer arithmetic with no float error, currency-specific decimal rules (JOD 3 decimals/fils, custom 0/2/3), and the return contents including over/short against an expected amount — meaningful for a tool with no output schema.

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

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

Front-loaded with the core purpose and technique, then input forms, then return values, then the list mode — a logical order with little waste. It is one very long compound sentence plus a trailing web URL that adds no value to an agent, which keeps it short of 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?

For a read-only tool with a nested counts array, six optional parameters and no output schema, the description covers input formats, currency/precision handling, the list mode and the returned totals/over-short. It is silent on edge behavior — e.g. an invalid denomination for a currency, mixed note/coin disambiguation beyond the schema's kind field, or what an empty counts array returns.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents every field. The description still adds usable semantics: denominations may be given by value (50, 0.25) or by label ('50 JD', '¼ dinar'), and it explains what 'expected' produces (over/short) rather than just restating the field name.

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

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

States a specific verb and resource ('Count a cash drawer by denomination') plus the defining technique ('exact integer maths, no float errors'), which separates it from generic calculators like calc_expression or calc_split_bill. It also enumerates supported currencies and the custom-currency option, so an agent knows exactly what domain this covers before 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?

Usage context is clear: give counts per denomination, and set list=true to discover a currency's denominations first — a sensible discovery-then-count flow. It does not explicitly rule out alternatives (e.g. when to prefer calc_expression for a plain arithmetic total, or calc_split_bill for splitting), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is clear. The description adds useful behavioral context beyond annotations: it lists the return values (final balance, total deposits, interest earned, year-by-year table) and states domain constraints (rate –50–100%, 1 month to 100 years).

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 tool's purpose and remains dense with useful details. The first sentence is long but well-structured, and the subsequent sentences cover returns, constraints, and a web reference without excessive verbosity.

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 8 parameters, no output schema, and rich schema descriptions, the description adequately explains the calculation model, return values, and key constraints. It could be slightly more complete by noting edge cases or the effect of table=false, but it is sufficient for correct invocation.

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

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

Schema coverage is 100%, so parameter documentation is already strong. The description adds semantic meaning beyond the schema: it clarifies contribution timing (start or end of month), the interpretation of inflation as "today's money," and rate/duration bounds, which help an agent reason about the calculation.

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 ("Project savings") and clearly states the resource and mechanics (compound interest with initial deposit and monthly contributions). It distinguishes itself from siblings like calc_loan and calc_salary by focusing on savings growth with contributions and compounding options.

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

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

The description implies the tool's use case (projecting savings with compound interest), but it does not explicitly state when to use this tool versus alternatives such as calc_loan or calc_discount. No exclusions or conditional guidance are provided, leaving the agent to infer the appropriate context.

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

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

Annotations already declare readOnly/idempotent/closed-world, but the description adds behavior the annotations cannot: public holidays are not counted, weekend definitions are configurable, month-end arithmetic clamps (Jan 31 + 1 month = Feb 28/29), and results include weekday and Umm al-Qura Hijri date. These are exactly the edge cases an agent needs for correct invocation.

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?

Front-loaded and dense: two mode definitions followed by cross-cutting rules. Some parenthetical lists (weekend variants) are run-on, but nearly every clause carries operational information, so there is little waste.

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 9-parameter tool with no required parameters and no output schema, the description supplies defaults, output composition (weekday, Hijri date, multiple difference formats), edge-case arithmetic, and an alternative tool. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining cross-parameter semantics such as the inclusive end-day option, default Fri–Sat weekend, and the clamping rule for month/year additions. It does not restate every parameter but adds real interpretive 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?

Opens with an explicit two-mode statement, then names each verb and resource: 'difference: days between two dates' and 'add: add or subtract days, business days, weeks, months or years'. It also names the sibling it is not (calc_hijri) and distinguishes the modes from each other, so an agent can pick the right tool without opening any 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?

Gives clear conditions for each mode and explicitly routes Hijri conversion to calc_hijri. It does not mention other plausible alternatives such as calc_due_date or calc_age, so the routing is good but not exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the description's real contribution is computational behavior: stacked percents multiply, tax/VAT is applied after discounts, and money is rounded to the cent at each step like a till. Those rules materially affect results and are not in the schema. Return shape is only loosely sketched ('what you save', 'effective total discount').

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?

Front-loaded one-line summary followed by three compact mode clauses; nearly every phrase carries information. The trailing web-version URL is marginally useful context rather than tool-selection content, slightly diluting an otherwise tight description.

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

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

With 14 optional parameters and no output schema, the description does a good job mapping parameters to modes and hinting at returns (savings, effective total discount, cheaper-per-unit winner). It never gives an exact result shape for compare mode (e.g. per-unit prices for A and B), which is the remaining 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%, so per-parameter text is already handled (baseline 3). The description adds ordering semantics the schema cannot express: the second discount applies after the first, percents stack multiplicatively, and tax is added after discounts. The compare example ('0.5 for 500 g when unit is kg') also clarifies unit/amount relationship.

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?

Opens with a concrete framing ('Three shop maths jobs') and then names each mode with a specific computation: sale price after stacked discounts plus tax, reverse discount percent between two prices, and per-unit deal comparison. An agent can tell exactly what this does and how it differs from generic siblings like calc_percentage or calc_split_bill.

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?

Each mode is prefixed with its purpose ('sale:', 'reverse:', 'compare:'), which effectively tells the agent which mode to pick for which question. There is no explicit when-not guidance or named alternative tool (e.g. vs calc_percentage), 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?

Annotations already declare readOnly/idempotent/closed-world, so the safety profile is covered. The description adds valuable behavior beyond that: it lists what is returned (conception date, full-term date, weeks+days progress, trimester, days remaining, milestone timeline weeks 4–42, optional Hijri) and the disclaimer, though it stops short of describing response structure for the progress section.

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?

Dense but front-loaded: purpose first, then outputs, then the disclaimer and link. The enumerated output list is long but each item is informative; no filler sentences.

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

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

With no output schema, the description fully carries the burden by enumerating every returned artifact and the optional Hijri expansion, plus a scope disclaimer. An agent can call this correctly without further documentation.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond by naming Naegele's rule, the cycle-length range 20–45, and the day-3/day-5 embryo distinction, tying the parameters to their clinical meaning rather than just restating field names.

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

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

States a specific verb+resource ('Estimated pregnancy due date') and enumerates the three accepted starting points (LMP, conception, IVF transfer), which clearly separates it from nearby siblings such as calc_age, calc_date_diff or calc_hijri.

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?

Explains which input method to pick and notes 'Estimate only, not medical advice,' which sets the appropriate use context. It does not explicitly name alternatives or exclusions (e.g., use calc_date_diff for plain date arithmetic), 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?

Going well beyond readOnlyHint/idempotentHint, it discloses output behavior the agent could not otherwise predict: exact rational or surd roots, complex roots, 10-significant-digit fallback for cubics, Gauss–Jordan for systems, and detection plus parametrisation of no-solution/infinite-solution cases. Worked steps are also promised, which matters for how the result should be presented.

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

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

A single dense sentence front-loads the verb and the equation types, with progressively finer detail after it. It is information-rich rather than padded, though the website link and the "like the website" phrasing consume space without helping tool selection.

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 no output schema, the description carries the return-value burden and does so at a high level (exact roots, worked steps, precision, parametrised infinite solutions). It stops short of describing the actual response shape, so an agent knows what to expect conceptually but not structurally.

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 semantics: it maps each `type` value to the coefficient layout and spells out the accepted string encodings ("3/4", "-1 1/2", e-notation) that the schema only hints at with number|string. It does not explicitly restate the `system` augmented-matrix row shape, leaving that to the schema.

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

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

States a specific verb ("solve") and resource ("equations") and then enumerates exactly which equation families are in scope: linear a·x + b = c, quadratic, cubic, and 2x2/3x3 linear systems. That enumeration cleanly separates it from siblings such as calc_expression (arithmetic evaluation) or calc_fraction, so an agent can route 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 supported-type list implicitly defines when to use it and the coefficient formats accepted ("integers, decimals, fractions, mixed numbers, e-notation") tell the agent what input is legal. It never names an alternative tool or states an explicit when-not condition (e.g. use calc_expression for plain arithmetic), 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?

Annotations already establish read-only, idempotent, non-open-world behavior. The description adds valuable traits beyond that: safe parsing with no eval, 12-significant-digit results, and plain/scientific output modes.

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 core purpose is front-loaded, and the dense function/constant lists earn their place for a scientific calculator. Structure is weaker because most information is packed into one long semicolon-separated sentence, but there is little pure 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 complex expression evaluator with no output schema, the description is highly complete: it covers syntax, safety, angle units, variables, ans, precision, and output format. An agent has enough information to call it correctly.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema by documenting the expression language: operators, precedence, implicit multiplication, postfix operators, trig units, supported functions, constants, ans, and variables.

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

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

The description names the exact action and resource: evaluate a maths expression safely with the site's own parser. It distinguishes itself from broader calculator siblings by specifying expression syntax, functions, constants, and precision.

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 is implied by 'Evaluate a maths expression', but the description never states when to choose this over calc_equation, calc_percentage, or other calc siblings. There are no explicit exclusions or routing cues.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower, but the description still adds real behavioral value: results are exact and never rounded, big integers are used, worked steps are returned, and approximations are small-denominator and flagged as such. It doesn't describe error handling for malformed expressions or the exact shape of the returned steps, and there is no output schema to cover that gap.

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

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

A single dense paragraph that front-loads the core capability before mode-by-mode detail — nothing is buried. The trailing web-version URL is the only content that doesn't help an agent invoke the tool, and the mode list is somewhat compressed into one long sentence, but overall it earns its length.

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, enum-driven calculator with no output schema, the description covers what each mode does, the accepted input syntax, and roughly what comes back (exact value, steps, percent, ordered list). The only meaningful gaps are error behavior on invalid expressions and the concrete shape of the returned steps, which the absence of an output schema leaves undone.

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

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

Schema coverage is 100% and the schema already supplies per-mode input examples, so the baseline would be 3. The description earns an extra point by adding syntax rules the schema omits: operator set (+ − × ÷ ^, brackets), the precedence rule that a/b binds tighter than ÷, the convention that brackets mark the repeating part, and the input separator style for compare.

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?

Opens with a specific verb+resource framing ("Exact fraction maths with big integers... and worked steps") and then enumerates all four modes with concrete input examples. An agent can distinguish this from sibling calculators like calc_expression, calc_equation, or calc_percentage purely from the description, since fraction/mixed-number/repeating-decimal handling is called out explicitly.

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 selecting each mode (calculate vs decimal_to_fraction vs fraction_to_decimal vs compare) with representative inputs. It stops short of naming alternatives — e.g. it never says when to prefer calc_expression for non-fraction arithmetic or calc_percentage for percent work — so routing against siblings 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?

Annotations already establish readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds meaningful behavioral context: it splits cost between people, computes per-km/mile and per-100 costs, optionally compares a second car, and converts consumption units. It does not explain output formatting or rounding, but the added detail is substantial.

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 dense single sentence with semicolons, but it is front-loaded with the main purpose and covers the major optional features efficiently. The web-version link is extraneous but minor; no sentence is entirely wasted.

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

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

For an 11-parameter tool with nested comparison options and no output schema, the description explains the core outputs (fuel needed, total cost, per-distance cost, per-100 cost, split cost, comparison results, unit conversion). It does not specify the output shape or rounding behavior, but it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including units and defaults. The description restates the key inputs and their relationships, adding a useful overview but little semantic detail beyond what the schema provides. Baseline 3 is appropriate when the schema carries the explanatory burden.

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 specific verbs and resources: it computes fuel needed and trip cost from distance, fuel price, and consumption, with optional splitting/comparison. This clearly distinguishes it from sibling calculators like calc_split_bill or calc_unit_convert, and an agent can identify its function immediately.

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 it by listing supported scenarios (round trips, people splitting, second-car comparison, consumption conversion), but it never explicitly says when to choose this over alternatives like calc_split_bill or calc_unit_convert. Usage is clear enough from context but lacks explicit routing guidance.

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

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

Annotations already declare readOnly, idempotent, and closed-world, so safety is covered. The description adds real behavioral detail beyond that: courses missing credits or with invalid grades are skipped and listed in the result, the 40-course cap, and the default 35–100 percent window. Return shape is only loosely sketched.

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

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

A single dense paragraph that leads with the three outputs before detailing scales and edge cases. Slightly packed, with the scale enumeration taking substantial space, but every sentence carries operative information.

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

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

With 8 params, a nested course array, and no output schema, the description must carry return-value context; it names the three computed figures and the skipped-course listing. Exact output field names are not given, which is the remaining 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% so the baseline is 3, but the description genuinely enriches the terse schema: it spells out what each scale means ('4.3 (A+ = 4.3)', '5.0 (A+ 5, A 4.75 … F 1)') and that percentMin/percentMax default to 35 and 100, which the schema does not state.

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 opening clause names specific verbs and resources: credit-weighted semester GPA, cumulative GPA, and the required average for a target. It immediately tells an agent the three distinct computations available, which no sibling calc_* tool offers.

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 implicitly defines the conditions for each mode: supply previousGpa/previousCredits for cumulative output, and targetGpa with remainingCredits for the target average. It also states input constraints (max 40 courses, percent scale needs min/max). No explicit 'do not use for X' exclusion is given, but no sibling competes directly.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the supported 1300–1600 AH range and that output is bilingual with Arabic-Indic digits and regional Gregorian month styles. It says nothing about what happens for out-of-range or invalid dates, nor about the exact shape of returned results for a tool with four distinct modes.

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?

Front-loaded with the core purpose, then a compact mode enumeration and the constraints. Dense parentheticals earn their place as disambiguation, though the trailing web-version URL adds nothing an agent can act on.

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 no output schema, the description does the work of hinting at returns per mode (month length plus Gregorian start/end; Hijri and Gregorian ages plus next Hijri birthday; bilingual output). That is close to complete for a read-only converter; only exact field names/shapes and error behavior remain unspecified.

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 per-mode parameter docs (date, hijriYear 1300–1600, hijriMonth 1–12 with Ramadan noted, birthDate, onDate) already carry the semantics. The description largely repeats that ground: the range 1300–1600 AH appears in the schema too, and the Arabic-Indic/Levant options duplicate the enum descriptions. Baseline 3 is right.

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

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

States a specific verb and resource ('Convert between Gregorian and Hijri dates' with the Umm al-Qura calendar) and enumerates the four operating modes, so the agent knows exactly what the tool does. It does not, however, differentiate itself from nearby siblings such as calc_age or time_convert, even though it contains an 'age' mode that overlaps with calc_age.

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 mode list effectively tells the agent which inputs select which operation (to_hijri takes a Gregorian date, to_gregorian needs Hijri y/m/d, month reports a Hijri month's length and boundaries, age needs a birthDate). There are no explicit 'use this instead of X' exclusions or prerequisites, 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?

Adds real behavior beyond the readOnly/idempotent annotations: an end time at or before the start is treated as an overnight shift, there is a cap of 6 shifts per day (the schema only caps totals at 42), and overtime is applied daily first and then weekly. These are non-obvious rules that change how the tool computes results, though no error handling or limits on the pay output are described.

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 front-loaded block that leads with the core purpose and then layers in shift rules, rounding, overtime and pay without repetition. Despite the density, every clause carries a distinct rule; even the reference URL is a single trailing token.

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

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

Covers the input rules and describes the outputs it produces (per-shift/day/week totals in h:mm and decimal, plus pay), which matters since there is no output schema. It leaves minor gaps such as invalid-time behavior and how currency interacts with pay, but nothing an agent needs to form a valid call 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 already 100%, so the baseline is 3, but the description goes further by explaining the interaction between dailyOvertimeHours and weeklyOvertimeHours (daily first, then weekly), the meaning of roundMinutes (5/6/15-minute shift rounding), and the default 1.5 multiplier. That interaction semantics is not obvious from the schema alone.

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

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

"Weekly time card: add shifts... Totals per shift, per day and per week" gives a specific verb (compute/add shifts) and resource (weekly time card with pay), which an agent can distinguish from neighbors like calc_salary or doc_attendance_sheet by inference. It stops short of naming an alternative explicitly, so it is clear rather than sibling-differentiating.

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 weekly-shift framing implies when the tool fits, but there is no explicit when-to-use or when-not guidance and no mention of alternatives (e.g. use calc_salary for a flat salary rather than shift-based hours). The agent must infer the selection condition from context.

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

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

Annotations already cover safety (readOnly, idempotent, closed-world), and the description adds genuinely new behavioral facts: arithmetic is in whole cents, the final payment absorbs rounding so the balance hits exactly 0, and extra monthly payments report interest saved and payoff acceleration. That is real determinism/output context beyond the structured hints, though nothing is said about input validation failures or edge behavior at rate 0.

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

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

A single dense sentence front-loads the return values, then packs the extra-payment and schedule behavior, constraints, and a reference URL. Every clause carries information, though the 'Maths is in whole cents like the website' phrasing is slightly chatty and the trailing link is decorative rather than operational.

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 seven parameters, no output schema, and a computational tool, the description enumerates the return payload (payment, total interest, total paid, payoff month, interest saved, amortization schedule) and bounds the inputs. An agent has everything needed to call it and to know what comes back.

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 earns an increment by adding constraints the schema omits — the 0–100% rate band, the 1-month-to-100-year term band, and the fact that extraMonthly yields interest-saved/payoff-shortening output, and that schedule can be yearly, monthly, or none.

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 the exact outputs (monthly payment, total interest, total paid, payoff month) for a fixed-rate loan or mortgage, plus the optional extras. A verb+resource+scope statement this specific lets an agent distinguish it from neighboring calculators like calc_compound_interest or calc_salary 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?

Usage is implied by the domain ('fixed-rate loan or mortgage') and bounded by stated ranges (rate 0–100%, term 1 month to 100 years), but there is no explicit when-to-use/when-not-to-use guidance or named alternative. An agent must infer that this is the right tool when a loan amortization is wanted rather than, say, compounding.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds the otherwise-undocumented return contract (number, display string, worked formula) and a reference URL, which is real value since no output schema exists, though it says nothing about error handling for missing per-mode fields.

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

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

A single dense sentence front-loads the scope and then walks the modes in order; almost every clause earns its place. The trailing web URL is mildly incidental and the sentence is long, but nothing is padded or repetitive.

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 9-parameter, mode-driven calculator with no output schema, the description supplies the complete mode→field matrix plus the return shape. An agent has everything needed to construct a valid call for any mode.

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