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

Goes well beyond annotations with rich behavioral details: nothing is changed/written, empty reply is an error, citation checking isn't done, truncation threshold (48k chars), specific ranges kept (28.8k + 14.4k), truncated=true flag, 180s model timeout, and 120s MCP timeout. Annotations only say readOnlyHint=true, so this adds substantial value.

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 core purpose, then details on truncation, timeouts, and alternatives. Dense but every sentence earns its place. Slightly long but appropriate given the 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?

Given no output schema, the description fully explains return fields (file, language, analysis_type, analysis, line_count, char_count, truncated, visible_lines). Covers access restrictions, timeout behavior, and truncation logic. Complete 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 coverage is 100%, so the schema already documents both parameters. The description adds that 'analysis_type picks the focus' but doesn't add meaning beyond the enum descriptions. Baseline 3 is appropriate when schema does the heavy lifting. The file_path parameter's sophisticated access rules are fully 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?

Specific verb+resource: 'Review one text file with Guaardvark's local LLM (Ollama) and return its written findings'. It explicitly distinguishes itself from siblings by pointing to read_code (for reading) and codegen (for changed copies).

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?

Clearly states the tool's role and names alternatives: 'To read the file yourself use read_code...; for a changed copy, codegen.' However, it doesn't explicitly state when to use this tool vs. other analysis siblings like get_repository_map, though the purpose 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 only declare readOnlyHint=true, but the description adds substantial behavioral context: it lists the JSON report contents, explains redirect, timeout, and size limits, discloses that private and local addresses are refused, and notes dependency on web access settings and a backend. It does not contradict 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 purpose and usage guidance are front-loaded, and the detail is relevant for a tool with many output blocks and constraints. The main report sentence is dense and run-on, but most information earns its place given the tool's complexity.

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

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

Even without an output schema, the description explains the returned report structure, block types, and defaults. It also covers prerequisites, safety limits, and alternatives, making it complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents the parameters well. The description ties analysis_type to output blocks and notes query behavior, but it largely repeats structured field semantics rather than adding syntax or format details beyond the schema.

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

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

The description states a specific verb and resource: 'Audit one public web page's SEO live and return a JSON report.' It also distinguishes the tool from siblings by naming fetch_url for reading a page and web_search for finding pages, so an agent can route without opening the schemas.

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

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

It gives explicit use cases ('audit a page's title and description') and names the alternatives ('to read the page use fetch_url, to find pages web_search'). It also states prerequisites and restrictions, including web access being off by default, the backend requirement, and refusal of private/local addresses even after redirects.

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; the description reinforces and extends this by stating it 'reads only; records nothing and holds nothing' — a meaningful clarification for a tool that simulates a gate capable of holding changes. It also discloses the output shape (verdict plus per-finding rule, file:line, why), which annotations do not cover. No contradiction with readOnlyHint.

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 outcome, then input mechanics; no filler or marketing language. The second sentence is a long run-on that duplicates some schema parameter text, costing a little crispness but still earning its place by explaining mode 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 usefully enumerates the verdict taxonomy and finding structure, and covers read-only behavior. Minor gap: it never states what happens if neither range nor filepath is supplied, which matters given zero required parameters.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds something the schema does not: that range and filepath/new_text are alternative modes ('Give either ... or ...'), plus the consequence of omitting old_text as a whole-file replacement. The old_text/new_text semantics themselves largely restate 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?

States a specific verb and resource — read/evaluate a code change the way the inbound guard would before it lands — and names the three possible verdicts (allowed, held, blocked). An agent can tell this is a pre-landing simulation/dry-run rather than a general code read. It stops short of explicitly naming the closest sibling (verify_change), so the differentiation is inferential.

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 'before it lands' framing clearly sets the usage context, and the description spells out the two mutually exclusive input modes (git range vs. single-file filepath/new_text/old_text), which is real routing guidance. It does not, however, say when to prefer this over siblings like verify_change or analyze_code.

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 flag destructiveHint=true, and the description substantiates it with the overwrite semantics ('replacing any file of that name there'), the read-only guarantee on input_file, the 10 MB and context-window refusals, the 180 s model / 120 s MCP timeout behavior with idempotency_key replay, and fence-stripping/error-on-no-code behavior. This is unusually rich disclosure beyond the annotations.

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

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

Front-loads the core operation well, but it is a single sprawling block whose timeout sentence ('...over MCP the call returns an error after its timeout (120 s by default); the run is not cancelled and saves if the model answers within 180 s of the start...') is convoluted and hard to parse. Information-dense but not cleanly structured.

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

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

For a complex generation-and-write tool with no output schema, the description covers inputs, refusal conditions, timing, idempotency, and the full return shape (output_path, filename, language, counts, syntax_ok, preview). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema carries field-level detail and a baseline of 3 applies. The description still adds cross-parameter semantics the schema does not: input_file is read-only and can never be the output, and output_filename's presence is what selects rewrite vs new-file mode.

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 ('Ask Guaardvark's local LLM ... for a complete version of a code file and save its reply as data/outputs/code/<output_filename>') and explicitly distinguishes itself from siblings by directing review-only use to analyze_code and non-code use to generate_file. An agent can identify the operation 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 explicit when/when-not branching: with input_file the model rewrites that file, without it the model writes from instructions alone, and calls are refused if instructions ask to improve/refactor/rewrite an existing file. It also names the alternatives (analyze_code, generate_file) and their selecting conditions.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false). The description adds substantial behavior beyond that: the job-id/polling model over MCP, the wait_for_result 60s cap, model 'auto' fallback ordering, the steps floor being silently raised, and file-type security refusals. This is rich disclosure that the annotations do not provide.

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

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

Front-loaded with purpose and when-to-use before the exclusions and the MCP flow, so the most important routing signal comes first. It is fairly long and packs in edge cases (consent, security, timing), but nearly every sentence carries distinct, useful information.

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

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

For an 8-parameter mutation tool with no output schema, the description covers the return contract (job id vs. waited result), the consent/security caveats, and the exclusion set. An agent has everything needed to invoke it and interpret the response 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 workflow meaning that ties parameters together – the job-id return and get_generation_status polling, the 'auto' model fallback, and the wait_for_result timing – which helps an agent understand parameter roles in context rather than restating 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?

Opens with a specific verb+resource: 'Edit an existing image using a natural-language instruction.' It then names the exact siblings it must not be confused with (generate_image, generate_identity, outpaint_image, remove_background), so an agent can route correctly without opening another 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?

Explicit when-to-use (user attached/uploaded an image and asks to add/remove/change something), an explicit exclusion ('Do NOT use this to make a brand-new image'), and named alternatives for adjacent tasks (generate_image, generate_identity, outpaint_image, remove_background). Guidance is complete and actionable.

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

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

Annotations only declare readOnlyHint=true, so the description carries real weight and delivers: JavaScript is not run, scripts/styles/nav/footers are stripped, private/local addresses are refused even after redirect or DNS change, the backend requirement is stated, and the JSON return shape is enumerated. This is far beyond what the annotation provides.

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 the routing rule, then return shape, then preconditions and refusals. The single dense paragraph earns most of its clauses, though the parenthetical CSS-stripping list and the redirect/DNS caveat could be trimmed slightly.

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 specifies every returned field (url, final_url, title, description, content, content_length) including the empty-title case and the truncation marker. Combined with the access prerequisites and refusal conditions, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and the schema already documents redirects, timeouts, the 2 MB cap, URL refusal, and the stopword-based stretch selection. The description largely restates that same behavior, so it meets the baseline rather than adding new parameter meaning.

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

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

States a specific verb and resource ('Read one public web page live') plus the scope ('ANY question about a specific webpage or domain'), and explicitly routes the agent away from web_search and analyze_website. An agent can distinguish this from every sibling 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?

Gives named alternatives with their selecting conditions ('For open-ended searches use web_search; for a title and meta-description audit use analyze_website'), plus a concrete example usage and the precondition that web access must be enabled.

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 and idempotentHint, and the description reinforces this and adds real context beyond the annotations: reads are live from the database (recently added items appear), document records report indexed/searchable status, and 'all'+no-name returns per-kind counts. No contradictions.

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

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

Purpose is front-loaded in the first clause and every sentence carries concrete information about coverage or filtering behavior. It is dense and reads as a run-on wall of text, 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?

With no output schema, the description carries the burden of describing returns, and it does: kind 'all' with no name returns counts, otherwise records are listed, and documents expose index status. It is complete enough to call the tool correctly, though return shape details (fields per record) are left implicit.

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 value: name matching is case-insensitive across name/title/filename, and the semantics of combining kind 'all' with/without a name are behavior not present in the schema. The project-parameter scope listing slightly differs from the schema's wording, but overall it enriches the parameters.

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

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

States a specific verb ('Look up') and resource ('the records Guaardvark keeps'), enumerates the exact record types it covers, and clarifies it mirrors the content pages. It also distinguishes its scope from the search sibling by noting it records existence while search_knowledge_base searches inside documents.

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?

Clearly explains the kind/name combinations (kind 'all' + name searches every kind; kind 'all' + no name returns counts) and routes the agent to search_knowledge_base with a project id for in-document search. It gives solid situational context but does not explicitly address when to prefer this over siblings like list_documents.

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 declare readOnly=false and destructive=false, so the description carries most of the burden and does well: it discloses the async job model, that the call returns a job id immediately, that get_generation_status is the polling companion, and how wait_for_result changes behavior. It stops short of covering cost, expected runtime, or failure modes, hence not a 5.

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

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

Front-loaded with the core action, then the mechanism, then usage routing, then the async contract. The middle im2img/model-list aside is dense but informative; no sentence is filler. Slightly heavy for a description but each clause earns its place.

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

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

With no output schema, the description correctly takes on the return-value burden by explaining that the call returns a job id and how to retrieve the final file. Combined with explicit async/sync semantics and sibling routing, an agent has everything needed to invoke and follow up 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 every parameter including strength ranges, frame bounds, and wait_for_result semantics is already documented in the schema. The description's mention of motion ('each later frame by img2img') adds light conceptual context but no format or syntax beyond what the schema provides, matching the baseline 3.

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

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

States a specific verb and resource (generate a looping GIF or frame-morph MP4) and even explains the generation mechanism (frame 1 from prompt, later frames via img2img). It explicitly names the sibling it is not, generate_video, so an agent can route correctly without opening either 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 explicit when-to-use triggers ('animate, create a GIF, or make a looping frame morph') and an explicit exclusion with the alternative ('for a cinema clip from a video model use generate_video instead'). Nothing is left to inference.

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

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

Although annotations only say readOnlyHint=false / destructiveHint=false, the description goes far beyond that: async job with immediate job_id/file-path return, filename -001 collision suffixing, one-row-at-a-time generation with the file written only at job end, per-call 180 s timeout, up to 4 retries then row drop, and a failure threshold (less than a quarter succeed, 30% above 10 rows) that leaves no file. That is exactly the operational detail an agent needs for a long-running job.

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 in the first clause, and for a tool this complex most sentences earn their place. However, it is a single dense run-on paragraph with nested parentheticals and semicolon-separated asides, which hurts scanability; some of the constraint detail could be broken into distinct 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?

There is no output schema, so the description must cover returns — and it does (job_id plus the output-folder path, with the collision-suffixed name), along with how to poll for completion and what 'complete' reports. For a complex, async, write-capable tool the coverage is complete.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters (including the idempotency_key retry behavior and the -001 suffix rule). The description reinforces a few cross-parameter interactions (client match injecting saved details, row N naming with quantity), but adds little syntax or meaning the schema does not already carry. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and artifact: 'Start a background job ... that writes a WordPress import CSV with Guaardvark's local LLM', and even describes the row structure. It explicitly distinguishes itself from the closest siblings (generate_wordpress_content, generate_enhanced_wordpress_content, generate_csv), so an agent can route correctly 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?

It states the operating precondition ('Over MCP the Guaardvark backend must be running'), the follow-up action (poll get_generation_status with job_id), and names the two alternatives with the exact condition that selects each ('For one page returned as text use ...; for a table of arbitrary data, generate_csv'). Nothing about when to choose this tool 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 flag this as a non-read-only, destructive operation, and the description goes well beyond that: 180 s cutoff, whole table in one reply, save location under csv/<filename>, and overwrite of an existing file of that name. It also enumerates the exact failure conditions (empty reply, no table, header only, mismatched row widths) and states nothing is saved in those cases.

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 purpose, then mechanism, then return values, then error semantics, then sibling routing — a logical order with no filler sentences. It is dense and on the long side for a tool description, but every clause carries information an agent needs to call it correctly.

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

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

Despite having no output schema, the description fully documents the return payload (path, column count and names, row_count versus rows_requested) and the failure modes. For a generative, side-effecting tool with five parameters, an agent has everything required to invoke and interpret it.

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

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

Schema description coverage is 100%, so filename, row_count, idempotency_key, include_headers and data_description are already fully documented in the schema. The description reinforces a few semantics (row_count is an instruction not an enforcement, header excluded from the count) but adds no parameter detail the schema lacks. 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?

States a specific verb and artifact ('Write one CSV table with Guaardvark's local LLM from a description of the data') and immediately scopes the mechanism (invents rows from the description alone, no file or document read). It explicitly names the sibling tools it is not: generate_bulk_csv and generate_file.

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

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

Gives explicit routing: generate_bulk_csv for a WordPress import file with a generated page per row (and notes it is a polled background job via get_generation_status), and generate_file for any other kind of file. The 'when not to use' condition is stated rather than implied.

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

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

Annotations only supply readOnlyHint=true, but the description adds substantial behavior beyond that: nothing is written to disk, the 180s per-model-call cutoff, the 120s default MCP timeout, one retry then error, and the specific failure modes (KB unsearchable, empty-index fallback, malformed CSV row). It even warns that two clients' documents in one index can mix.

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 and mostly front-loaded, but delivered as a single run-on paragraph of very long sentences, which makes the many constraints (timeouts, retry, error cases, return shape) harder to scan than necessary. Nothing is wasted, but structure is poor.

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

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

Despite no output schema, the return contract is fully described: a single CSV row of seven double-quoted columns with no header, the exact column order, and the MCP JSON shape {row, sources}. Combined with the error and timeout semantics, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the schema already documents all 10 parameters and the baseline would be 3. The description adds genuine semantic value on top: it clarifies how client/topic/services feed the KB search and that primary_service + secondary_service constrain which services the model may write about (empty = no limit).

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 ('Compose one WordPress page') and immediately scopes it ('grounded in the user's own indexed documents'), which clearly separates it from the plain generate_wordpress_content sibling. The mechanism (search KB, rerank up to 6 passages, 500+ word HTML) is spelled out.

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 routes the agent: 'Without grounding or service limits use generate_wordpress_content; for many pages in one import file, generate_bulk_csv.' This names both alternatives and the conditions that select them, so no inference is required.

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

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

Annotations declare destructiveHint=true, and the description earns that by explaining exactly what is destroyed: a file already at that name is replaced. It further discloses that output goes under data/outputs/files, that an empty model reply is an error writing nothing, and that generation uses the description ALONE without reading existing files.

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 what it does, then the replacement/error behavior, then the routing rules. Every sentence is load-bearing, though the sibling-routing block makes it longer than typical; the 'not offered over MCP' aside is minor overhead.

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 destructive mutation tool with no output schema, the description covers destination path, replacement semantics, failure behavior, and routing to correct alternatives. Nothing an agent needs to invoke it safely 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 all five parameters (including idempotency_key retry semantics) are already documented in the schema. The description adds little parameter-level detail beyond clarifying that content_description is the sole source of content; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a brand-NEW output file from a description') and immediately scopes it, then explicitly distinguishes it from codegen, edit_code, generate_csv, and generate_bulk_csv. An agent can route correctly 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 explicit when-not guidance ('Do NOT use it to improve, refactor, modify, or produce a new version of an existing file') with the reason (it cannot see the file and would fabricate), and names the correct alternatives with conditions (codegen with input_file for grounded copies, generate_csv for tables, generate_bulk_csv for WordPress imports).

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=false and destructiveHint=false, so the safety profile is already covered and the lower bar applies. The description still adds real context: the return shape (image URL vs. batch id to poll via get_generation_status) and that omitted arguments default to wait_for_result=false over MCP. It stops short of permissions, cost/rate limits, or GPU-contention behavior.

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, then return behavior, then routing to alternatives, then the character/LoRA caveat. Every sentence carries a distinct operational fact — no filler or repetition.

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

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

For a 9-parameter generation tool with no output schema, the description supplies the return format, polling path, default-argument behavior, and sibling routing. An agent has everything needed to call it correctly on the first attempt.

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 cross-parameter semantics the schema does not: subject_ids must be a separate parameter (never nested in prompt) and overrides model selection behavior, and it reiterates the MCP default for wait_for_result. This meaningfully exceeds restating field docs.

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 ('Generate a new image from a text prompt') plus execution locus (this machine's GPU). It also names the sibling tools it is not (edit_image, remove_background, generate_video), so an agent can distinguish it 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 an explicit trigger ('Use when the user asks to create, generate, draw or visualize an image') and explicit alternatives with their selecting conditions (edit_image for changes, remove_background for cutouts, generate_video for video). The subject_ids routing rule and its trap ('naming the character only in the prompt does not load its LoRA') leave nothing 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 only say readOnlyHint=false / destructiveHint=false, so the description carries the rest and does so richly: async job_id return, expected latency ('30-second song usually takes one to two minutes'), failure modes for the plugin not running and for the un-installed 1.5 model ('refused otherwise, never downloaded'), and idempotency semantics. This is context an agent cannot get from structured 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?

Dense but front-loaded: capability first, then return/polling contract, then prerequisites, then sibling disambiguation. Nearly every clause carries operational information; the model-enum sentence overlaps with the schema, which is the only mild redundancy.

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

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

There is no output schema, and the description compensates fully by explaining the return value (job_id, then file name, library document id and download link after polling) and where the artifact surfaces (Studio Audio page). For an async generation tool with a plugin dependency, nothing an agent needs to call and finish the task 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 prose adds interpretation beyond the schema: it glosses the style prompt as 'genre, instruments, mood, tempo, voice' and frames lyrics as optional with the instrumental fallback. The model enum behavior is largely duplicated from the schema, which keeps this from 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+resource ('Make a song ... with ACE-Step in Guaardvark's Audio Foundry') and immediately scopes what the tool produces (style prompt + optional lyrics, up to 240s, sung or instrumental). It also distinguishes itself from the two nearest siblings, generate_speech and generate_music_video, by name.

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

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

Gives explicit routing rules ('For a spoken line use generate_speech; for a music video set to a song, generate_music_video'), names the prerequisite (Audio Foundry plugin must be running), and states the required follow-up action (poll get_generation_status with the returned job_id). Conditions that select alternatives are all present.

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 thin annotations, it discloses substantial behavior: it uploads/attaches the song, writes cut prompts, and stops at the approval gate without spending GPU rendering clips. This tells the agent exactly how far the side effects go and that it is a gated, non-rendering operation.

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

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

Front-loaded with the core action, then the approval-gate constraint, then usage, then the alternative and parameter guidance. Every sentence carries distinct information with no filler.

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

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

For a 5-param, 2-required project-creation tool with no output schema, the description covers purpose, scope, side effects, usage conditions and alternatives. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real routing value for 'song' by explaining that a document id comes from generate_music or may be an audio file location. It clarifies intent over the schema's detailed format list.

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 (Start a project) with a concrete resource (music-video project) and scope (from a song and a visual style). It clearly differentiates itself from siblings generate_music, generate_video and start_film_crew, so an agent can route without opening 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?

Explicitly says 'Use when the user asks to make a music video' and names the alternative routing rule: 'For a story from a screenplay, use start_film_crew.' It also ties the song input back to generate_music's output, covering both when-to-use and the sibling handoff.

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 declare readOnlyHint=false and destructiveHint=false; the description goes well beyond, disclosing the ~1 minute wait, the returned fields, the job_id long-read fallback, and the refusal cases (uninstalled model/voice pack, chatterbox+voice combination) with a pointer to Manage models. This is exactly the mutating-tool context the annotations cannot 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?

Dense but front-loaded: purpose and return behavior come first, then constraints and refusal cases. It is long, but almost every sentence carries an actionable constraint rather than filler, so it stays on the right side of verbose.

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

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

With no output schema, the description compensates by describing the return shape (file name, library document id, length, download link) and the job_id alternative. For a complex multi-engine, mutating tool this is complete enough 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 coverage is 100%, so the baseline is 3 and the schema already documents all four parameters. The description adds value on top by explaining cross-parameter interaction and refusal behavior (e.g. 'engine chatterbox with a voice is refused', voice selection forcing Kokoro), which goes slightly beyond the field-level 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?

States a specific verb+resource ('Turn text into speech on this machine') and names the engine/plugin backing it. It also explicitly distinguishes itself from the sibling generate_music ('For a song use generate_music'), so an agent can route without opening either 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 concrete when-to-use and when-not guidance: split scripts over 3000 chars, poll get_generation_status on a job_id and 'do not call again', and use generate_music for songs. It also states the prerequisite (Audio Foundry plugin running) and the cloning restriction, leaving little 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 only declare readOnlyHint=false / destructiveHint=false, so the description carries the real burden and does: it discloses the async-queue contract (returns immediately with a batch id and deep-link so long jobs are not false-timeouted), idempotent retry semantics, silent-family failure for audio=true, model-clamping and refusal behavior ('never rendered on another model'), and reference-build requirements.

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?

Five dense sentences that are front-loaded with the queue/return contract before routing advice. Slightly long and there is mild overlap between the description's parameter advice and the schema text, but almost every clause earns its place.

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

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

For a 16-parameter async mutation tool with no output schema, the description still reports what the call returns (batch id plus Studio deep-link) and covers the main behavioral forks. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all 16 parameters; the baseline would be 3. The description adds genuine decision logic beyond the schema by explaining which model/audio combination yields a soundtrack, what first/last_image are for, and which reference inputs lock identity/motion/voice.

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 ('Queue a video clip from a text prompt using a local video model') and immediately differentiates itself from siblings by naming generate_animation for looping frame-morph work. An agent can tell it apart from generate_image, generate_animation and generate_music_video 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 an explicit trigger ('Use when the user asks to create, generate, or make a video'), a named alternative with the condition that selects it ('For short looping frame-morph animations use generate_animation instead'), and routing rules for model choice, audio, frame animation and reference builds.

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 declare readOnlyHint=true; the description adds substantial behavioral context beyond that: nothing is written to disk, no document lookup occurs, one retry then error on malformed output, a 180 s per-model-call cutoff, and a 120 s MCP timeout. It also enumerates the specific failure modes (not six fields, missing title/HTML, HTML or line breaks outside the content column).

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 operation and output contract, and every sentence carries information. It is dense and slightly cramped in the final sentence about timeouts, but there is no filler or repetition.

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

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

No output schema exists, so the description must carry the return contract, and it does fully: column order, headerless CSV, quoting, and the exact error conditions. Combined with the timeout disclosure and the no-side-effect guarantee, an agent has everything needed to call and interpret this 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 baseline would be 3, but the description adds meaning the schema does not: row_id is the value written to the ID column, the ID column is always row_id, and the page derives from the parameters alone. Some content (website is context-only, word_count is not enforced) duplicates the schema text, capping this 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 (compose one WordPress page) plus the exact output shape (a single six-column CSV row with named columns). It explicitly distinguishes itself from both relevant siblings, generate_enhanced_wordpress_content and generate_bulk_csv, so an agent can route without opening either 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 explicit when-to-use-this conditions ('from the parameters alone, with no document lookup') and names both alternatives with the condition that selects each: enhanced for grounding in indexed documents and named services, bulk for many pages in one import file. Nothing is left to inference.

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

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

Annotations only declare readOnlyHint=true, but the description adds substantial behavioral context: backend dependency, staleness (reflects last analysis, later edits absent), failure behavior for unanalysed folders, parsing limitations for Python/JavaScript/TypeScript only, and omission of third-party imports and isolated files.

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 well-structured: it front-loads the return shape, then the parsing constraints, then usage routing, then behavioral caveats. Every sentence carries information useful for correct invocation.

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

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

For a tool with no output schema and a complex nested return object, the description fully documents the JSON shape, key semantics, edge cases, staleness behavior, and failure mode. An agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, and the schema already explains that folder_id is an integer id of an analysed folder and where to find it. The description repeats 'Take folder_id from list_code_repositories' but adds no syntax, format, or constraint beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource: returns the file-level import graph of an uploaded Code Repository folder. It also distinguishes itself from siblings by naming get_repository_map for ranked symbol overview and map_codebase for import cycles in Guaardvark's own checkout.

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

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

Explicitly says to take folder_id from list_code_repositories and gives two clear alternative tools with the conditions that select them. It also states when the graph may be empty or fail, so an agent knows when this tool applies and when it does not.

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 declare readOnlyHint=true, so the bar is low, yet the description adds real behavior: unknown filenames return a short notice rather than an error, and ambiguous filenames short-circuit to a document_id list with no outline. These are exactly the edge cases an agent would otherwise mis-handle.

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: the core output description comes first, then workflow placement, then error/ambiguity behavior. The parenthetical about '(no section)' is slightly nested and long, but every sentence carries required 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?

No output schema exists, so the description must describe return values, and it does: sections, pages, passage counts, a total header, a short notice for unknown files, and a document_id list for ambiguous names. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the conditional logic behind document_id (only needed when several files share a filename) and explains that read_document_section must receive heading/page labels exactly as this outline prints them. That is meaningful semantics 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 ('Show the structure of one indexed document') and enumerates exactly what the structure contains: heading paths, pages in order, passage counts, and a total. It is immediately distinguishable from read_document_section, list_documents, and search_knowledge_base.

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 position in a workflow ('after list_documents and before read_document_section') and names the alternative for a different intent ('To find a topic across documents use search_knowledge_base'). Even the disambiguation branch (call again with document_id) is prescribed.

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 (readOnlyHint, idempotentHint), and the description goes well beyond them: it discloses the exact failure modes (unknown id is an error, silent backend is an error, the backend must be running over MCP), what each status value means, and what progress reporting looks like per job type.

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 and the prose is dense with no filler sentences, but the full enumeration of every producing tool and every return field in one long run-on sentence is heavier than strictly necessary.

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: status, elapsed time, per-stage progress, per-type file results, and error surface. Nothing needed to call or interpret it 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 both parameters are already documented, but the description adds real meaning the schema does not: it maps each id prefix (ImageBatch_, bulk_gen_, tooljob_, 32-char song id) to the tool that produced it, which is the key to choosing the right id.

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 ('report the state of a queued generation') and then enumerates exactly which id families it accepts and which sibling tool produced each. An agent can identify this tool and its scope 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?

'Use after a queued generate call, or when the user asks whether a render is done' gives a clear triggering context, and the wait_seconds parameter is framed as the alternative to repeated polling. No explicit when-not or named sibling alternative, 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 only declare readOnlyHint=true; the description goes well beyond that by disclosing the ~4,096-token truncation, the dependency on the Guaardvark backend, the staleness semantics (reflects last analysis, not later edits, with timestamp and file count on line one), and concrete failure behaviors (not a Code Repository, not analysed, no symbols found).

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 return contract, then prerequisites, then failure modes, then siblings; nearly every clause carries information. It is dense and runs long, but there is little waste and the ordering is sensible.

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: it describes the return format and truncation, the input prerequisite chain, staleness/timestamp behavior, failure modes, and empty-result handling. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100% and the folder_id description already states has_metadata=true, the subfolder caveat and to use the top folder's id, so the description largely repeats structured data. It adds the cross-reference to list_code_repositories as the source, but no new syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Return the stored architecture overview of an uploaded Code Repository folder') and immediately characterizes the payload (Markdown, files by PageRank, up to 10 top-ranked symbols, ~4,096 token cap). It is clearly distinguishable from map_codebase, get_dependency_graph and read_ast_node, which it names.

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

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

Explicitly tells the agent where to get folder_id (list_code_repositories, has_metadata=true) and routes to alternatives with conditions: get_dependency_graph for import edges, read_ast_node for a single Python symbol's source, map_codebase for Guaardvark's own checkout. Usage and exclusions are fully covered.

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 mark it non-read-only and non-destructive; the description adds substantial behavior beyond that — model fallback order (Qwen-Image-Edit then FLUX Kontext), refusal with the pack name when neither is installed, async job-id return over MCP, wait_for_result's 60s cap, and idempotency behavior. It does not discuss permissions or output file format, but for a local edit tool that gap is minor.

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: the core purpose leads, then model resolution, then sibling disambiguation, then async semantics. Every sentence carries information, though it is longer than strictly necessary for routing.

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 compensates by explaining what the call returns (job id) and how to retrieve the file (get_generation_status, or wait_for_result). Combined with the 100%-covered schema and the alternatives, an agent has everything needed to call and follow up 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 schema already documents image, steps, instruction, idempotency_key, and wait_for_result in detail. The description reinforces the instruction semantics and the async/wait behavior but adds little parameter detail beyond the schema.

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

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

States a specific verb+resource ('change or remove something in an attached photo') with a natural-language instruction, and immediately distinguishes itself from siblings: edit_image is the same operation, outpaint_image is for canvas extension, generate_identity is for new scenes outside MCP. An agent can route 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?

Explicit when-to-use versus alternatives: 'either name works' for edit_image, 'for extending the canvas use outpaint_image', and generate_identity for a brand-new face scene. It also tells the agent how to get results (poll get_generation_status unless wait_for_result) and how the missing-model case behaves.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds value by specifying exactly what live state is inspected (nvidia-smi, lock, model slots, plugins), which goes beyond the annotations and gives the agent a clear picture of the tool's scope.

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

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

Two concise sentences. The first states the purpose and enumerates the inspection targets, the second gives usage triggers. Everything earns its place with no fluff.

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

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

For a zero-parameter, read-only inspection tool with safety annotations, the description fully covers the purpose and when to use it. The inspection targets imply the nature of the output, and the annotations handle safety, so nothing essential is missing.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Per the guidelines, a baseline of 4 is appropriate for 0-parameter tools; the description needs no parameter explanation, and it doesn't waste words on 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?

The description clearly states the tool's purpose: 'Inspect live GPU state' and enumerates the specific aspects (nvidia-smi, exclusive lock, orchestrator model slots, plugins running). This is specific and distinguishes it from any sibling tool that might touch GPU-related concerns.

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

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

The description explicitly lists trigger phrases: 'debug GPU issues', 'what's using VRAM', 'GPU status', or 'OOM'. This gives an agent concrete cues for when to invoke the tool, and no alternative tool in the sibling list covers GPU inspection, so no exclusions are needed.

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

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

Goes well beyond the readOnlyHint annotation: it enumerates what is omitted (git-ignored data, venv, node_modules, dist/build, logs, __pycache__, symlinks, .env/credentials), states the 1,500-entry truncation with a remainder note, and notes that paths outside the checkout are refused.

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 dense single paragraph but front-loaded with the core behavior and output shape, then exclusions, then depth/truncation, then alternatives. Every clause carries information, though the exclusion list is long and the base verb 'list' is buried under 'Show a folder'.

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 duty and does so — indented tree, folders first, sizes, and truncation note. For a 2-param read-only listing tool this is complete.

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

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

Schema coverage is 100%, so both parameters are already documented. The description restates max_depth semantics and the directory default, adding little beyond the schema, which matches the baseline for fully covered parameters.

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

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

States a specific verb ('Show') and resource ('a folder of this Guaardvark install's own source as an indented tree') with output shape (folders first, sizes). It explicitly differentiates from siblings by naming search_code, read_code, and list_code_repositories.

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 routing: 'Use read_code to open a file, search_code or search_codebase to find one by content, and list_code_repositories for repositories indexed in the Library.' It also states when contents are excluded and advises 1-2 depth on large folders.

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 declare readOnlyHint=true; the description adds substantial context beyond them: backend must be running, subfolders are marked separately, only has_metadata=true entries have been analysed and the map/graph are built at the end of that analysis, and 'live' is not a folder id. These are non-obvious behavioral facts an agent needs.

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

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

Front-loaded with the core action and return shape, then the routing guidance, then the has_metadata caveat and the 'live' note. It is dense and longer than average, but nearly every clause carries distinct operational information; only mild tightening is possible.

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 spells out the returned fields, the special 'live' entry, and the has_metadata gating that determines downstream usability. Combined with the annotation covering read-only safety, an agent has everything needed to call and interpret this tool correctly.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate beyond parameter syntax, and the description correctly spends its words on return-value semantics instead.

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

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

States a specific verb and resource ('List the folders marked as Code Repositories in Guaardvark') and goes further by declaring the exact return shape as a JSON array of {id, name, path, has_metadata, description}. It also explicitly distinguishes the special 'live' entry from real folder ids, so an agent can tell it apart from siblings like get_repository_map.

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

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

Explicitly tells the agent to 'Call it first to get the integer folder_id that get_repository_map, get_dependency_graph and read_ast_node take', naming the dependent tools. It also gives the selection rule for has_metadata=true and the top-folder-id case, plus routing for the 'live' entry to search_code/read_code/map_codebase.

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 provide readOnlyHint, but the description adds substantial behavioral detail: ordering by passage count, line format, duplicate filename handling with document_id, indexing scope, and pagination continuation behavior. This is far beyond what the annotation declares.

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 actionable detail. Each sentence covers a distinct concern: output format, file coupling, duplicate handling, scope, parameter behavior, and alternatives, with no filler.

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

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

Given a tool with no output schema and minimal annotations, the description fully explains the return format, ordering, pagination, duplicate-name disambiguation, and index coverage. An agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100%, so the schema already documents limit, offset, and name_contains. The description restates their functions but adds no syntax or constraints beyond what the schema provides, making 3 the appropriate baseline.

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

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

The description gives a specific verb and resource: list documents in the local knowledge base. It also names the exact output shape and distinguishes this tool from nearby siblings such as search_knowledge_base and summarize_corpus.

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

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

It explicitly says to use this to see what is indexed and to get filenames for get_document_outline and read_document_section. It also gives alternatives for topic search and corpus summaries, so when-not-to-use is covered.

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 supply readOnlyHint, so the description carries the behavioral burden and does so richly: no backend/network/GPU, cache staleness at 5 minutes, 60 s wait bound, status 'computing' fallback, background computation limited to one per folder, and no duplicate computation on re-call. It also discloses the read-only static-analysis nature and the offline subprocess when mapping the whole checkout.

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 return values are front-loaded, then operational behavior, then sibling routing last. It is long and clause-dense, but nearly every clause carries non-obvious information, so little reads as padding.

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 compensates by enumerating return fields and finding attributes (id, kind, severity, summary, up to 6 paths) and by explaining omission of dismissed findings. Combined with the caching and timeout semantics, an agent has everything needed to call and interpret the result.

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 meaning beyond the schema: it clarifies the limit/finding_count relationship and the full refresh lifecycle (wait up to 60 s, otherwise last map or 'computing' arrives while a new map computes in the background). Those details meaningfully change how an agent should set the flag.

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 ('Run the System Mapper over Guaardvark's own source checkout, or a folder inside it') and enumerates the return shape (file_count, languages, per-analyzer stats, finding kinds). It explicitly names the sibling tools it is not for the uploaded-repo and semantic-search cases, so an agent can distinguish it 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?

Gives explicit routing: uploaded Code Repository folders go to get_repository_map or get_dependency_graph, meaning-based lookup goes to search_codebase. It also states the operational conditions for when to set refresh=true versus relying on the cached map.

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

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

Discloses behavior far beyond the annotations: repeat-safety of play/pause/stop vs. act-every-call semantics of next/previous/toggle, Linux-only/MPRIS2 constraint, and the exact error path that lists open players with their status. Annotations only say non-read-only and non-destructive.

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 transport, followed by resolution rules and return examples. It is long but nearly every sentence carries actionable information; minor verbosity in the parenthetical example strings.

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, and the description supplies the return contract itself (the player acted on, the reason it was picked, or an error listing candidates). For a 3-parameter tool with a single enum required argument, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: the player-name matching rules (D-Bus suffix, case-insensitive, 'vlc' matching 'vlc.instance<pid>') and the full default-selection order for omitting it. It does not elaborate on idempotency_key beyond what the schema already says.

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 set (play/pause/stop/next/previous/toggle) and the exact resource (an MPRIS2 media player on the D-Bus session bus of this machine). It also explicitly scopes itself against siblings: it works on any MPRIS2 player, not just the VLC media_play starts.

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 default-resolution algorithm (the VLC Guaardvark started, else the only player open, else the only playing) and the failure behavior when ambiguous, plus explicit routing to media_play, media_volume and media_status for other jobs.

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 supply readOnlyHint=false/destructiveHint=false; the description carries the real behavioral load, disclosing that new music replaces the previously Guaardvark-started VLC, user-opened players are untouched, one-instance mode is disabled, up to 50 tracks play, matches/directory play in order unless shuffle is true, and the return-string format. This is far beyond annotation coverage.

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 organized around the query/directory/neither branches, with zero filler sentences. It is dense and somewhat run-on, but the length is justified by the tool's real branching complexity and every clause conveys a distinct rule.

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, state-mutating player-invocation tool with minimal annotations and no output schema, the description covers return format, none-match errors, path allow/deny rules, shuffle defaults, and cross-tool interactions. Nothing an agent needs to call 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 already 100%, so the baseline is 3, but the description adds semantics the schema lacks: that only the file name plus its immediate folder are matched (parent folders ignored, so artist names don't match), the 50-track cap, and the idempotency/retry behavior. It adds genuine meaning over the structured fields.

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 ('Play local music files in VLC on the machine running this Guaardvark server'), scopes it to Linux, and clearly separates itself from the media_control/media_volume/media_status siblings by naming each one's role. An agent can identify the tool 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?

Explicit routing: query searches by keyword, 'music'/'all'/'songs'/'everything' plays everything, directory plays a named folder, and with neither it resumes. It also states when to defer to siblings ('Pause or skip with media_control, set loudness with media_volume, see the current track with media_status').

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces this ('without changing anything') while adding the Linux-only constraint and a detailed selection algorithm. It also documents the full text return format, which exceeds the annotation bar. It stops short of 5 only because failure modes beyond 'No media player is running' (e.g. D-Bus unavailable) are not covered.

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 selection rules, then return format, then sibling routing. It is a dense single paragraph, but every sentence earns its place; the enumerated return fields are long yet necessary given there is no output 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 no output schema, the description must explain return values, and it enumerates every line (Player, Chosen, Status, Title, Artist, Album, Length, volume, Other players) plus the empty case. Combined with the selection algorithm and sibling routing, an agent has everything needed to call and interpret the 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% and the schema documents the player-name format in detail, so baseline is 3. The description earns above baseline by carrying the semantics the schema defers to it ('Omit to use the default described above'), fully specifying the fallback chain an agent must rely on when the parameter is omitted.

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 ('Report what a media player ... is playing') and immediately scopes it to Linux, MPRIS2, and read-only. An agent can tell it apart from the media_play/media_control/media_volume siblings 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 routes to alternatives ('Start music with media_play; for system volume use media_volume; to pause or skip use media_control') and states the condition for each. Also defines the default player-selection fallback chain, so the agent knows exactly when to pass a player and when to omit 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 only declare readOnlyHint=false and destructiveHint=false; the description adds substantial context beyond that: Linux-only, ALSA Master affecting every application, the returned strings ('Volume: 30%', ' (muted)', 'Volume set to N%'), rounding, capping above 100 with a notice, and the repeat/idempotency behavior of absolute vs relative steps.

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 read/change behavior and keeps every clause informative, though the parenthetical detail about return strings and clamping makes it denser than strictly necessary for a 2-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?

With no output schema, the description carries return-value explanation fully ('Volume: 30%', 'Volume set to N%'), plus platform limits and sibling routing. 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 already 100%, so the baseline is 3, but the description adds genuine semantic value the schema does not: how '+10'/'-10' differ from '50' on repeat, that decimals are rounded, and that values over 100 are clamped and reported. It still leaves the idempotency_key semantics largely to 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 precise verb+resource: reading or changing the system output volume (ALSA 'Master' via amixer) on the machine running the server. It explicitly scopes the effect as system-wide rather than player-only, which separates it cleanly from media_control and media_status.

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

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

Tells the agent exactly how to read (omit level) versus write (supply level), enumerates the accepted level forms, and routes to siblings: 'Use media_control to pause or skip, media_status for the current track.' When-to-use and alternatives are both 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?

Annotations only declare readOnlyHint=false and destructiveHint=false. The description goes far beyond that, disclosing the model dependency and its fallback behavior, the asynchronous job-id-then-poll flow over MCP, the wait_for_result / 60s timeout semantics, and idempotency behavior. These are substantive operational traits not derivable from structured 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?

Front-loaded with the core action, then usage triggers, prerequisites, alternatives, and the async contract in a logical order. Dense and information-rich, though the two async explanations (in the description and the wait_for_result schema field) are somewhat redundant.

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

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

For a 9-param mutation tool with no output schema, it covers the full call lifecycle: prerequisite model, fallback behavior, async polling, idempotency, and sibling routing. Nothing an agent needs to invoke and interpret the call correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning: it explains the FLUX Kontext fallback of ignoring canvas growth, the async wait_for_result flow, and reinforces the steps floor of 20 and idempotency retry behavior. It still largely overlaps the schema, keeping it below 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 ('expand... fill the new area') and resource ('attached photo') with clear directional scope. It distinguishes itself from siblings by naming edit_image and remove_background and explaining the different intent behind each.

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 gives trigger language ('extend, expand the canvas, or outpaint') and routes the agent to alternatives: edit_image to change contents, remove_background to cut the subject. It also states a prerequisite (Qwen-Image-Edit must be installed; FLUX Kontext alone won't add canvas), which is exactly the kind of when-not guidance agents need.

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 substantial context beyond the sparse annotations (readOnlyHint=false, destructiveHint=false): the draft lands in a queue at status='drafted', nothing posts until human approval on the Approvals page, YouTube URLs get scouted, include_link grading behavior, and idempotency semantics. Rich behavioral disclosure that the annotations do not 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 purpose and the no-post constraint, which is good. However, some clauses are dense and run-on (the include_link and share-mode sentences), and a few details duplicate what the schema already states, making it longer than necessary.

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 10-param mutation-adjacent tool with no output schema, the description covers the important workflow (queue, approval, mode differences, return of a drafted item). It could mention what the tool returns (draft id/status) but the approval-queue framing largely substitutes.

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 cross-parameter logic the schema lacks: the mode='comment' vs mode='share' dependency (platform must be reddit in share mode, share_link defaults to guaardvark.com, target_url ignored in share mode). This is meaningfully beyond the per-field 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?

States a specific verb+resource ('Draft a social outreach comment or share post') and immediately clarifies what it does NOT do ('does NOT post'). The description distinguishes itself from the sibling request_publish by explicitly naming it at the end.

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

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

Explicit routing: use this for drafting queue items, use request_publish for the user's own connected accounts. Mode-specific requirements (comment needs thread_context or target_url; share requires reddit + share_target) are spelled out, so an agent knows exactly when each mode applies.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered, and the description adds genuinely non-obvious behavior: approved items are returned oldest-first (posting order) while all other statuses are newest-first, plus the default row count. It omits pagination or row-field details, but for a read-only list call this is solid added context.

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

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

A single dense paragraph, front-loaded with the purpose and default, then ordering semantics and limit. No filler sentences; every clause adds 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?

For a simple two-parameter read-only list tool with full schema coverage and no output schema, the description covers default behavior, per-status ordering, and result count. Nothing an agent needs to call 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 description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying status values to intent (the default is 'waiting for review', 'approved' is queued-to-post order, 'posted' is history) and restating the limit default. The ordering relationship between status and result order is value the schema alone does not convey.

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

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

States a specific verb and resource ('List social outreach drafts') and scopes it by status, which cleanly separates it from siblings like outreach_status, outreach_draft_post, and outreach_reject_draft. An agent knows immediately this is the read/list entry point for the outreach draft pipeline.

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

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

Gives clear context for each status value, including that the default 'drafted' means waiting for review and that 'posted' serves recent history. It does not mention alternative tools (e.g. outreach_status) or when not to use this list view, 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 declare destructiveHint=true, and the description adds substantial context beyond that: the resulting row state ('rejected'), that nothing will publish even if the draft was already picked up, and the irreversible failure case once submission/posting has begun. This is exactly the behavioral detail an agent needs for a destructive call.

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 action and its success condition, then the failure edge case, then the usage trigger. Four sentences with little waste, though slightly more expansive than strictly needed.

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 destructive mutation with no output schema, the description fully covers the outcome state, the irreversibility boundary, and the caller trigger, while annotations carry the safety profile. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so both 'id' and 'idempotency_key' are already documented in the schema. The description only says 'by id' and adds no syntax or format meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb ('Reject') and resource ('an outreach draft by id') plus the effect ('so it will not post'). An agent can distinguish it from siblings like outreach_draft_post or request_publish 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?

Gives an explicit trigger ('Use when the user says "kill that one", "don't post draft 42"') and states the preconditions under which the call will fail (already submitting or posted). It does not name a specific alternative tool, but the when-to-use guidance 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 declare readOnlyHint=true, and the description reinforces the read-only nature by saying 'Get the current state'. It adds useful context about what the state includes, which goes beyond the annotation. No contradictory or hidden side-effect behavior is suggested.

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

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

The description is two sentences with no wasted words. The first sentence states the operation and result; the second quickly gives concrete user-phrase triggers. This is efficient and well front-loaded.

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

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

For a parameterless, read-only status tool, the description is complete: it names the domain, the state components returned, and the conversational triggers. The sibling-tool context is handled by the explicit 'outreach' scope. No output schema exists, but the described categories are enough to interpret the result.

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

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

The input schema has no parameters, so there is nothing for the description to clarify. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on the tool's outcome rather than parameter details.

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 ('Get'), a clear resource ('the social outreach loop'), and the exact data points returned ('enabled / supervised / cadence per platform'). This makes it easy to distinguish from sibling outreach tools like outreach_draft_post or outreach_list_queue, which involve different actions.

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

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

The description provides explicit trigger examples ('is outreach on?', 'how many posts today?', 'what's the outreach status?'), giving clear guidance on when to call this tool. It does not enumerate exclusions or alternatives, but for a parameterless status tool, the positive use cases are sufficient.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description nonetheless adds substantial context beyond it: no OCR (scanned PDFs return empty), the 10 MB size cap, dependency requirements for .xls/.xlsb, and error behavior for damaged/password-protected files. Under the calibration this is well beyond a 3, but it does not describe pagination or return-shape nuances beyond the header line; given annotations carry safety, a 4 is warranted. I'll score 4.

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?

Long but information-dense; every format clause earns its place and the header output format is front-loaded. Slightly verbose with the parenthetical header template, but not 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?

No output schema exists, yet the description explains the header line and per-format extraction semantics, plus failure modes. An agent has everything needed to call it correctly and interpret the result.

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 file_path parameter already documents path resolution, refusal patterns, and hidden-folder rules in depth. The description adds no parameter-specific semantics, so the baseline 3 applies.

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

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

States a precise verb and resource ('Extract the text of one document or image') and then breaks down behavior per file format, so an agent knows exactly what it produces. It also names the sibling tools it is not (search_knowledge_base, read_document_section, read_code), making it easily distinguishable.

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 routes the agent: 'For documents already indexed use search_knowledge_base or read_document_section; for source code, read_code.' It also clarifies the operation writes and indexes nothing, which is a key when-to-use signal.

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 declare readOnlyHint=true, so the description carries the rest and does so richly: it discloses snapshot semantics ('reads the file as it is on disk now'), a backend dependency, and an enumerated failure list (non-.py, absolute paths, out-of-folder paths, missing file, syntax errors, name-not-found). Multiple matches and the '# Match N' header format are also disclosed.

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

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

Dense but front-loaded: purpose first, then behavior, then failure modes, then alternatives. Every sentence carries distinct routing or behavioral information with no filler.

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

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

No output schema exists, and the description compensates by describing the match-header return format. Combined with the failure semantics and sibling routing, an agent has everything needed 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 baseline is 3; the description adds value beyond it by explaining bare-name matching at any depth ('Worker.run' does not match, 'run' does) and that all same-named definitions are returned. It reinforces rather than merely duplicating 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 (return the source) and resource (one Python class or function, decorators included) with explicit scope contrast to the whole file. The sibling it is not — read_code — is named, so an agent can distinguish it without opening 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?

Explicitly routes: use get_repository_map to find names, use read_code with 'data/uploads/' for the whole file. It also states the prerequisite (Guaardvark backend running) and the conditions under which it fails, leaving little to inference.

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

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

With readOnlyHint already declaring safety, the description adds rich behavioral context: 10 MB file limit, 60,000-character per-call cap, pagination header format ('Showing lines A-B of N'), return structure (header with path, counts, SHA-256, mtime; content without line numbers), and a detailed refusal list including .git, venv, .env, and key files. It also distinguishes MCP versus chat absolute-path handling.

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, beginning with the core operation and size/pagination constraints before listing refusals and alternatives. Some redundancy exists, such as repeating that relative paths cannot leave the checkout, but most sentences carry actionable 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?

Given the tool's complexity, the description covers file size limits, pagination behavior, return format (even without an output schema), refusal rules, and sibling alternatives. An agent has enough detail to call the tool correctly and interpret its output without guessing.

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 useful context—start_line/end_line correspond to line numbers reported by search_code, and pagination continuation uses the next page's start_line—but it also says 'a range past the end of the file is an error,' which conflicts with the schema's end_line note that 'A value past the end of the file reads to the end.' This inconsistency reduces reliability.

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: 'Read one UTF-8 text file ... from this Guaardvark install's own checkout, whole or by line range.' It distinguishes itself from siblings by naming alternatives for different file types and tasks (search_code, search_codebase, process_file, read_logs). An agent can identify the exact operation 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?

It gives explicit routing: 'To find a file use search_code or search_codebase; for PDF or Office files process_file; for logs read_logs.' It also explains when to use start_line/end_line and covers refusal conditions, leaving little ambiguity about alternatives or prerequisites.

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 declare readOnlyHint=true, and the description adds substantial behavioral context: 25 passages per call, 1,200-character truncation, section/page labelling matching the outline, total-plus-offset in the header for the next call, and the duplicate-filename case that returns a document list with no text. These are exactly the operational traits an agent cannot get from the annotation.

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

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

Front-loaded with purpose and then dense with functional detail; essentially no sentence is filler. It is delivered as one long unbroken block, which makes the parameter-combination rules and pagination behavior harder to scan than they need to be, but nothing 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?

With no output schema, the description still covers return shape (passages, truncation, section/page labels, header totals and next offset) and the ambiguity path (shared filenames returning document_id). For a 5-parameter read 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 baseline is 3, and the description goes further by explaining that any heading_path is matched case-insensitively as a containing substring (so a short value can return several sections) and that '(no section)' targets unheadinged, unpaged passages. It also clarifies that offset reads past the first 25 and that both params together narrow to a section on a page, though much of the per-parameter wording overlaps 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?

States a specific verb (read) and resource (stored text of an indexed document) and immediately differentiates itself from retrieval siblings with 'without searching, in document order.' An agent can distinguish it from search_knowledge_base and get_document_outline from the first clause 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?

Explicit routing: locate a topic first with search_knowledge_base, use get_document_outline to obtain heading_path/page_label, and process_file for files that are not indexed. It also enumerates the three parameter combinations (heading only, page only, both, neither) and their outcomes, leaving little to inference.

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

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

With readOnlyHint=true already declaring a safe read operation, the description adds valuable behavior beyond annotations: credentials are automatically masked with ***, and logs never written are reported as not found. These are important operational details for an agent interpreting the output.

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 purpose, then usage triggers, then security/not-found behavior. Every sentence earns its place, though the user-utterance examples make it slightly longer than a minimal definition.

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 log-tail tool with no output schema, the description covers purpose, invocation cues, credential masking, and missing-log behavior. The schema handles parameter details, and no critical context is missing.

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

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

Schema description coverage is 100%, so the schema already defines the name enum, lines range/default, and query filter semantics. The description reinforces that files live under logs/ and lists categories, but adds little parameter-level meaning beyond the structured 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 ('Tail') and resource ('one of Guaardvark's log files under logs/') and enumerates the log categories, making it immediately clear what the tool does. An agent can distinguish this from sibling tools that read code, documents, or other resources.

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

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

It provides explicit user-utterance triggers: 'review the logs', 'check backend.log', 'celery errors', and 'what did the last crash say'. It does not name alternative tools or state when not to use it, but the context is clear and sufficient for selection.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real load: it explains that over MCP the call returns a job id immediately and must be polled via get_generation_status unless wait_for_result is true (with the 60 s cap), and that chat runs inline. This is behavioral detail well beyond what annotations provide.

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

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

The first sentence front-loads the core purpose and output, and each subsequent sentence covers routing, invocation, or async behavior. It is dense but every sentence earns its place; slightly long but not 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?

Covers purpose, sibling differentiation, chat vs MCP invocation, input sourcing rules, and the async job/polling contract. With no output schema, the description still tells the agent exactly how to obtain the resulting file, leaving nothing material missing for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents all three parameters thoroughly. The description still adds cross-context meaning, notably that chat uses the attached image when image is omitted while an MCP client must pass image, and restates the poll/wait semantics. It adds a bit of value but largely echoes 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+resource ('Remove the background from an attached photo and return a transparent PNG') and explicitly distinguishes itself from siblings edit_image and generate_identity, naming what each does instead. An agent can route between these 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 explicit use cases (product shots, stickers, cut-outs) and explicitly rules out related alternatives by naming edit_image and generate_identity with their differing behaviors. It also clarifies the chat vs MCP invocation difference and when to poll versus wait.

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 say readOnlyHint=false and destructiveHint=false; the description adds the critical non-obvious trait that the call does NOT post immediately but waits on the Approvals page for a human to approve, reject or cancel, regardless of publish settings. It also discloses the return shape (publish record ids and status).

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 scope, then the approval-workflow caveat, then routing. Every sentence is informative, though the tool's behavior is packed into a fairly dense block of prose rather than being more scannable.

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

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

There is no output schema, so the description compensates by stating the return value (publish record ids and status). Combined with the approval-workflow disclosure and the sibling routing, an agent has everything needed to call this 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, but the description adds genuine semantics for 'connection' beyond the schema: the omissibility rule when a single text connection exists and the accepted identifier forms. It does not explain link_url or idempotency_key, but the schema covers those.

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