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

The readOnlyHint annotation already tells the agent this is a safe read operation. The description adds useful detail about what the analysis covers, but it does not disclose return format, whether the analysis is synchronous, or any limitations such as file size or language support. With annotations covering the safety profile, the description adds some context but not a robust behavioral picture.

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

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

The description is a single concise sentence with no filler. It front-loads the main action and lists focus areas efficiently. It loses one point because it is slightly generic and could include a brief note about output or usage without becoming 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 should at least hint at what the tool returns, but it only says what is analyzed. The readOnlyHint and 100% parameter coverage lower the burden, but the missing return-value context and lack of usage guidance make the description adequate rather than fully 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 both file_path and analysis_type are already documented in the schema. The description does not add any extra meaning about parameter semantics beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description uses a specific verb and resource: 'Analyze code files,' and enumerates the analysis dimensions (structure, patterns, best practices, improvements). This clearly distinguishes it from sibling read-only tools like read_code, but it does not explicitly state what makes it different from more focused analysis tools such as read_ast_node or get_dependency_graph.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention that read_code should be used for simply reading a file, or that search_code is better for finding specific symbols. The description implies analysis use but gives no explicit context, exclusions, or alternative recommendations.

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

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

Annotations already indicate readOnlyHint=true, so the description doesn't need to prove safety. The description adds value by listing what the analysis covers, but it does not disclose behavioral details such as whether the tool fetches the page live, how it handles errors, or what exactly is returned.

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

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

The description is a single, focused sentence with no fluff. It front-loads the primary action and resource, and every phrase contributes to understanding the tool's purpose.

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

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

The description gives a broad overview of outputs but no output schema exists, so the agent must infer what shape the insights take. With four parameters and no usage guidance, the description is adequate but not fully complete for an agent deciding when and how to invoke it.

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

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

Schema description coverage is 100%, so every parameter is already documented. The tool description doesn't add meaningful detail beyond saying the analysis includes content, SEO, structure, and insights, which loosely maps to analysis_type and include_metadata but doesn't explain parameter-specific behavior beyond the schema.

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

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

The description clearly states the action ('Analyze'), the resource ('website URL'), and the main outputs ('content, SEO information, structure, and insights'). It is specific enough to understand what the tool does, though it does not explicitly distinguish it from sibling tools like fetch_url or web_search.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention when to choose analyze_website over fetch_url, web_search, or analyze_code, and provides no exclusions 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 already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds that it generates 'complete, modified versions' and mentions 'preserve_structure' in the schema, but doesn't disclose what gets overwritten, whether the original file is modified in place, or any side effects. With annotations covering the destructive nature, a 3 is appropriate.

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

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

The description is a single sentence that front-loads the core action and outcome. It's concise and readable, though it could be slightly more specific about the 'complete, modified versions' phrasing. No wasted words.

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

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

For a code-generation tool with 6 parameters and no output schema, the description is adequate but not complete. It doesn't explain what the output looks like, whether the original file is modified, or how the 'preserve_structure' option behaves. The annotations cover the destructive hint, but an agent would benefit from knowing the return value or side effects.

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 6 parameters. The description adds no parameter-level detail beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states a clear verb ('Analyze' and 'generate') and resource ('uploaded code files'), and mentions producing 'complete, modified versions with requested changes'. It distinguishes itself from read-only siblings like analyze_code and read_code by emphasizing generation/modification. However, it doesn't explicitly name a sibling alternative, so it's clear but not fully differentiated.

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

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

The description implies usage: when you have uploaded code files and need modified versions. It doesn't explicitly state when not to use it or name alternatives like analyze_code for analysis-only or generate_file for new files. The context is implied rather than explicit, so it's adequate but has gaps.

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, and the description is consistent with both — no contradiction. Beyond the annotations, it adds a useful behavioral guarantee: 'Preserves the original subject and only applies the requested edit,' clarifying this is a targeted modification rather than a regeneration. It does not cover auth/rate-limit behavior, but the annotation safety profile lowers the bar.

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 sentences, front-loaded with the core purpose, followed by usage context and then alternative routing. Each sentence earns its place, though 'Preserves the original subject' is slightly redundant with the edit semantics and the exclusions could be tightened without losing routing value. Appropriately sized overall.

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

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

For a 7-param tool with full schema coverage, the description fully covers the primary invocation (attached image + instruction), the no-image fallback, and sibling routing. Minor gaps: it never mentions return format or whether edits are asynchronous, and model/reference-image decisions are left entirely to the schema. Acceptable but not exhaustive.

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

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

Schema description coverage is 100%, so baseline 3 applies. The description reinforces that the instruction is natural-language and that the flow assumes an attached image, but it adds no parameter-level meaning beyond what the schema already documents (image auto-use, model backends, steps, reference images, idempotency key). It does not need to compensate for any coverage gap.

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

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

States a specific verb+resource ('Edit an existing image using a natural-language instruction') and explicitly differentiates from siblings: 'Do NOT use this to make a brand-new image from scratch — use generate_image' and 'For a new scene that keeps a face from an attached photo, use generate_identity.' This cleanly disambiguates it from the many image-related sibling tools (generate_image, inpaint_image, remove_background, outpaint_image).

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 conditions ('user has attached/uploaded an image... asks to add, remove, or change something'), explicit when-not conditions ('Do NOT use this to make a brand-new image from scratch'), names the alternatives (generate_image, generate_identity), and even covers the failure case: 'If the user did not attach an image, ask them to attach one.' 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; the description adds meaningful behavioral context: truncation at ~2000 chars, the conditional behavior of the query parameter, and the caveat that without a query the top of a page is often navigation. No contradiction with annotations.

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

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

Three sentences with no wasted words: purpose is front-loaded, usage examples earn their place, and the alternative is named at the end. Ideal length for the information conveyed.

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 2-parameter read-only tool with no output schema, the description covers the return shape (title, meta description, main text), the query behavior, and the decision boundary vs web_search. An agent can correctly select and invoke the tool without further clarification.

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

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

Schema description coverage is 100%, so baseline is 3. Both url and query are already documented in the schema (including optional protocol handling and what query does). The main description does not add parameter-level detail beyond the schema.

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

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

The description states a specific action ('Fetch a specific URL') with a concrete result (page title, meta description, main text content up to ~2000 chars). It explicitly scopes the tool to known URLs/domains and contrasts with web_search for open-ended queries, distinguishing it from siblings.

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

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

Gives explicit when-to-use ('ANY question about a specific webpage or domain') with concrete example queries and an explicit when-not-to-use with a named alternative ('For open-ended searches without a specific URL, use web_search instead.'). The decision boundary is fully spelled out.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is not a read-only or destructive operation. The description adds useful context about Stable Diffusion img2img and looping output, but it does not disclose async behavior, status polling, or what artifact is returned. That leaves a moderate behavioral gap for a generation tool.

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

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

The description is three tight sentences: first states the core function, second gives usage triggers, third gives the exclusion. 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 7-parameter generation tool with no output schema, the description covers purpose, usage, and alternative well. However, it does not describe how the result is returned or whether generation is asynchronous, which would be useful for a tool that creates artifacts. The sibling get_generation_status partially compensates.

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 and the schema documents every parameter. The description loosely mirrors the motion and prompt fields but adds no extra semantics beyond what the schema already provides.

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 generates a short looping GIF or frame-morph MP4 from a text prompt with motion description, explicitly naming the output type and generation method. It also differentiates itself from generate_video, so the agent can distinguish it from adjacent tools.

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

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

It provides explicit triggers: 'Use when the user asks to animate, create a GIF, or make a looping frame morph.' It also names the alternative for cinema clips: 'use generate_video instead.' This is textbook when-to-use guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds the behavioral trait of concurrent processing and efficiency, which is useful context. However, it doesn't disclose what gets destroyed, whether the operation is idempotent (though the idempotency_key parameter hints at retry behavior), or any side effects beyond file generation.

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

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

The description is a single sentence that front-loads the core purpose and key differentiator (concurrent processing). It is concise and free of filler, though it could arguably be slightly more specific about the output format or scale.

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 8 parameters, 100% schema coverage, and no output schema, the description is adequate but not complete. It doesn't explain return values, error conditions, or the relationship between quantity and pages. The idempotency_key parameter is documented in the schema, but the description doesn't reinforce when retries are needed. Given the destructiveHint annotation, more context about side effects would improve completeness.

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. The description adds the context that 'quantity' relates to 'hundreds of pages' and that 'concurrent_workers' is the mechanism for efficiency, but it doesn't add meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('generate'), a resource ('bulk CSV files'), and a key characteristic ('hundreds of pages efficiently using concurrent processing'). It distinguishes itself from the sibling 'generate_csv' by the 'bulk' and 'concurrent processing' qualifiers, though it doesn't explicitly name the sibling.

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

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

The description implies usage for large-scale CSV generation with concurrent processing, which hints at when to use it over generate_csv. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions 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 declare destructiveHint=true, so the description should clarify what destructive behavior occurs (e.g., overwriting an existing file). The description only says 'Generate a CSV file' and does not disclose side effects, file overwriting behavior, or any other behavioral traits. With a destructive hint, the description carries a higher burden and fails to address it.

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

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

The description is a single sentence with no wasted words. It is front-loaded with the verb and resource, though it could be slightly more informative without becoming verbose.

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

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

Given the destructiveHint annotation and the existence of overlapping siblings like generate_bulk_csv and generate_file, the description is incomplete. It does not explain the destructive nature, when to prefer this tool over alternatives, or what the output looks like. The schema covers parameters, but the description fails to provide the behavioral and selection context an agent needs.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Generate') and resource ('a CSV file'), and mentions it is based on user specifications and data structure instructions. It is clear enough to distinguish from siblings like generate_bulk_csv and generate_file, though it doesn't explicitly name those alternatives.

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

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

The description implies usage for generating CSV files from user specifications, but it does not explicitly state when to use this tool versus generate_bulk_csv or generate_file. The context signals show siblings that overlap, so the lack of explicit routing guidance is a gap.

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

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

The description states 'Generate WordPress CSV content', which implies a write/create operation, while the annotations declare readOnlyHint=true. This is a direct contradiction. Additionally, the description offers no other behavioral disclosures such as side effects, permissions, or output characteristics, making it unreliable.

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

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

The description is a single, efficient sentence with the core action and object front-loaded. It contains no fluff or repetition, making it easy to parse quickly. However, the brevity comes at the cost of explanatory detail, which is acceptable for conciseness but not for completeness.

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

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

The tool has 10 parameters and a close sibling, yet the description fails to explain what 'enhanced' means, what 'topic constraints' are, or how it differs from generate_wordpress_content. With no output schema, the agent is left without information about the CSV format or content structure. For a generation tool of this complexity, the description is insufficient.

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 parameters are already documented. The description adds a vague reference to 'RAG-enhanced business intelligence' and 'topic constraints' that loosely connects to parameters like topic and client, but does not clarify specific parameter semantics beyond what the schema provides. Baseline 3 is appropriate given the high schema coverage.

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

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

The description clearly identifies a specific verb 'Generate' and a resource 'WordPress CSV content', and adds 'RAG-enhanced business intelligence and topic constraints' to indicate a specialized approach. However, it does not explicitly differentiate from the sibling generate_wordpress_content beyond the word 'enhanced', leaving some ambiguity about what makes it distinct.

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

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

The description provides no guidance on when to use this tool versus its siblings like generate_wordpress_content or generate_csv. There is no mention of conditions, prerequisites, or alternatives, leaving the agent to infer usage from the name alone.

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

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

The description meaningfully adds behavior beyond the annotations by disclosing that the tool never reads existing files and would fabricate if asked to modify one, which is a critical trust boundary. It also names the output directory. It does not clarify overwrite behavior or the save_to_disk=false case, but the destructiveHint annotation already signals the write-side risk.

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

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

The description is compact and front-loaded with the main purpose. Each sentence earns its place: core function, read-never guarantee, when-not-to-use warning, and replacement routing. There is no filler, repetition of schema defaults, or unnecessary elaboration.

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 write tool with no output schema and five parameters, the description covers the output location, generation source, and sibling differentiation, which is most of what an agent needs. The remaining gaps are whether a filename collision overwrites an existing file and what happens when save_to_disk is false, but the schema and annotations cover much of that context.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning by binding filename to the data/outputs/files directory and clarifying that content_description is the sole source of generation. This is modest but genuine added context 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 first sentence uses a specific verb, Create, with a clear resource, brand-NEW output file, and a concrete output location, data/outputs/files. The qualifiers brand-NEW and from description ALONE immediately distinguish this tool from codegen and other file generators, so an agent can tell what it does without opening the schema.

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

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

The description explicitly states when not to use the tool: do not use it to improve, refactor, modify, or produce a new version of an existing or uploaded file. It also names two alternatives, codegen with input_file and edit_code, with conditions attached, making the routing decision explicit 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 say readOnly=false, destructive=false, so the description carries the main burden. It adds behavioral detail: the server default is wait_for_result=false, and merely placing [batman_2] in the prompt without subject_ids 'will NOT load the LoRA.' This is meaningful behavior beyond the annotations, though side effects like rate limits or cost are not mentioned.

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 four tight sentences: core operation first, return value, use trigger, then the two critical caveats. Every sentence earns its place; the repetition about not burying subject_ids is emphatic and valuable, not filler.

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

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

With 9 parameters but full schema coverage, the description doesn't need to restate param details. It covers the only required input prompt, the output (URL), the key LoRA rule, and the default async behavior. The polling flow for async results is already explained in the wait_for_result schema description, 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?

Schema coverage is 100%, setting the baseline at 3. The description adds real semantic value by insisting subject_ids be a separate numeric array, giving a concrete example (subject_ids=[26]), and warning not to bury it in the prompt. It also reinforces the wait_for_result default in the context of the MCP server, which complements the schema.

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

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

The description opens with 'Generate an image from a text prompt,' a specific verb and resource, and follows with the output format ('Returns the URL of the generated image'). This clearly separates it from sibling editing tools like edit_image, inpaint_image, or video generation, even without naming them.

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

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

It gives an explicit trigger condition: 'Use when the user asks to create, generate, draw, or visualize an image.' It also explains the key prerequisite for cast characters (always pass subject_ids). It does not name alternatives or state when not to use it, so it stops short of a full exclusion guide.

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 significant context beyond annotations: it stops at an approval gate and does not spend GPU rendering, telling the agent this is a setup step, not a final render. It also states it uploads/attaches the song and writes cut prompts. Given annotations only indicate non-read-only and non-destructive, this behavioral detail is valuable.

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 with clear structure. The first sentence covers purpose and key behavior, the second gives usage trigger and parameter guidance. No unnecessary words, front-loaded with the most critical 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?

Covers the essential context: what it does, when to use, and a key limitation (no rendering). It does not describe the return value or what happens after the approval gate, but given no output schema and the tool's moderate complexity, this is not a critical gap. Could be improved by mentioning the output or next steps, but it is reasonably complete.

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

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

Schema description coverage is 100%, so parameters are already fully documented. The description repeats the song format instruction but adds no new meaning for other parameters like style_prompt or idempotency_key. It does not explain the idempotency behavior beyond the schema. Minimal added value, consistent with baseline for high schema coverage.

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

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

The description clearly states the action ('Start a music-video project from a song and a visual style') and details the workflow (uploads/attaches song, writes cut prompts, stops at approval gate). It explicitly distinguishes itself from siblings by noting it does not spend GPU rendering clips, which separates it from video generation tools like generate_video or generate_animation.

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

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

Provides an explicit trigger: 'Use when the user asks to make a music video.' It also clarifies scope by noting it stops before rendering, implying other tools handle rendering. However, it does not name alternative tools explicitly, but the instruction is clear enough for an agent to route correctly.

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 the real burden and does: it discloses async queueing, immediate return with batch id and deep-link, avoidance of false timeouts, and idempotency behavior. It stops short of stating auth/permission requirements or failure modes for silent-model audio requests, which keeps it just under 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 and return behavior, then usage, then model-selection guidance, then the sibling alternative. Dense for three sentences but every clause carries selection value; 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 15-parameter async generation tool with no output schema, the description covers the return contract (batch id, Studio deep-link), the sync/async toggle, and how to pick models and references. Nothing essential to 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 3 is the baseline. The description goes beyond the schema by tying parameters to outcomes: model='minimax-h3-int8' or audio=true yields a soundtrack/dialogue clip, first_image/last_image animate between frames, and reference_images/reference_audio lock a person or voice on the reference build. That relational guidance is genuinely additive.

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 (Queue), resource (video clip), and input (text prompt) plus the execution model (local video model). Explicitly distinguishes itself from the sibling generate_animation, so an agent can route 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 a clear trigger ('user asks to create, generate, or make a video'), names the alternative tool with the condition that selects it ('short looping frame-morph animations use generate_animation'), and tells the agent how to choose a model/settings for audio, frame interpolation, or identity locking.

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 no external mutation is expected. The description adds that the output is a CSV row with SEo-optimized content, but provides no further behavioral detail about how the content is generated, what format the row takes, or any limitations. It doesn't contradict the annotations, and with the annotation covering side effects, a 3 is appropriate.

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

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

The description is a single, front-loaded sentence with no filler. It states the core purpose immediately and is appropriately concise for a tool of this simplicity.

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

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

With no output schema, the description usefully identifies the output as a CSV row, but doesn't specify the row's column structure, whether it returns a string or file, or how it differs from the bulk/file-generation siblings. For the moderate complexity and the rich sibling context, this is adequate but has clear gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description echoes 'topic' and 'client' from the schema but adds little beyond that; it doesn't explain how row_id, website, or word_count affect the generated CSV row. The schema itself carries most of the 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?

The description names a specific verb ('Generate'), resource ('WordPress-compatible CSv row'), and two defining characteristics ('SEO-optimized content,' 'for a specific topic and client'). It clearly states what the tool produces, but it doesn't differentiate from its close sibling 'generate_enhanced_wordPress_content' or 'generate_bsv', so it misses top-tier sibling distinction.

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

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

The description implies usage: when you need a single WordPress-compatible CSV row for a given topic and client. However, it doesn't state when to prefer this over alternatives like 'generate_enhanced_wordPress_content' or 'generate_bulk_csv', nor does it mention any exclusions or preconditions. This is implied usage, not explicit guidance.

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

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

Annotations already declare readOnlyHint=true, and the description's 'Retrieve' and 'returns' are consistent. The description adds the output format (JSON string) which is useful, but it does not disclose any other behavioral traits such as performance limits, depth of analysis, or error conditions. Given the annotation coverage, a score of 3 is appropriate.

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

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

The description is two sentences with no filler. The primary action is front-loaded, and the return format is mentioned immediately. Every sentence contributes essential information without redundancy.

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

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

With a single parameter, a read-only annotation, and no output schema, the description adequately explains the return value ('a JSON string mapping files to the files they import'). It does not cover edge cases or error handling, but for a simple read-only tool this is sufficient. A 4 reflects good completeness given the low complexity.

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

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

The schema covers the only parameter (folder_id) with a description, achieving 100% coverage. The description only restates 'given a folder ID' without adding any new meaning, syntax, or constraints beyond what the schema already provides, so it meets the baseline but adds no extra value.

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

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

The description clearly states the tool retrieves a file-level import dependency graph for a folder ID, specifying the output as a JSON string mapping files to their imports. It is specific about the resource and action, but it does not explicitly differentiate from sibling tools like get_repository_map or map_codebase, so it misses the full distinction criterion.

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

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

The description provides a clear usage context: 'Use this tool to trace dependencies and understand how files interact.' However, it does not mention when not to use it or suggest any alternative tools, so it lacks explicit exclusions or sibling routing.

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

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

The description goes beyond the readOnlyHint annotation by describing what the tool returns: sections or pages in order, with passage counts. This tells the agent what kind of structural data to expect without needing an output schema. It adds useful behavioral context beyond annotation metadata.

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

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

The description is two tight sentences: the first states what the tool does, and the second gives context for when to use it. There is no filler, and the most important information is front-loaded.

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

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

This is a simple one-parameter read-only tool, and the description plus schema fully cover what an agent needs to call it correctly: what the tool returns, how to identify the document, and the recommended workflow context. No output schema is necessary because the return shape is described in plain language.

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

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

The schema already documents source_filename with 100% coverage, including 'as shown by list_documents.' The description adds only the idea of 'one indexed document,' which is marginal beyond the schema. Since the schema carries the burden, baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Show the internal structure of one indexed document — its sections or pages, in order, with passage counts.' It clearly distinguishes this from list_documents, which lists documents, and from retrieving content from a document. The scope is unambiguous.

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

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

The description explicitly instructs 'Use this after list_documents to see what is inside a document before retrieving from it,' giving clear sequencing and context for when this tool is appropriate. It does not explicitly name or exclude siblings like read_document_section, but the 'before retrieving' phrasing implies the distinction.

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, so the description does not need to restate safety. It adds value by disclosing the return shape: 'status, progress, and the URL of each finished file', which is particularly useful given there is no output schema. It also implies polling-friendly behavior by indicating the tool can be called to check completion.

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

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

Two sentences, front-loaded with the core purpose, followed by the source types, return values, and usage guidance. Every clause is necessary and there is zero redundancy.

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

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

For a one-parameter status-check tool with no output schema and read-only/idempotent annotations, the description covers what the tool does, what it returns, and when to use it. It also correctly handles both image and video batch sources. No critical information missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100% and the schema already explains batch_id as 'The batch id a generate tool returned (e.g. ImageBatch_09-11-2026_132620_013).' The tool description does not add meaning beyond the schema, only referencing the parameter in passing. Baseline 3 is appropriate since the schema carries the full semantic load.

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

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

The description names the exact verb-resource pair ('Report the state of a queued generation'), specifies the two source categories (ImageBatch_... and video batches), and details the return contents (status, progress, file URLs). It clearly differentiates from sibling status tools by identifying the specific generation calls it covers.

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

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

Provides explicit usage context: 'Use after a queued generate call, or when the user asks whether a render is done.' It does not name alternatives or exclusions, but for this tool the correct usage is clear from the generation-source context. Sibling status tools like swarm_status or media_status serve different domains, so no confusion is likely.

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

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

The readOnlyHint already indicates this is a safe read. The description adds meaningful context beyond the annotation by explaining that the map is PageRank-based, prioritizes important functions/classes, and shows relationships, which helps set expectations about output style.

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

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

The description is two concise sentences with the core action and resource front-loaded. Every sentence earns its place and no filler or repetition exists.

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, read-only, one-parameter tool, the description gives enough information to understand what the tool does and when to use it. It could be strengthened by clarifying how it differs from map_codebase and get_dependency_graph, but it is not incomplete for basic invocation.

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

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

The single parameter folder_id is fully described in the schema with 100% coverage, so the description adds no new semantic detail. The description merely restates 'given folder ID' without enriching the 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?

The description clearly identifies the resource: a PageRank-based architectural repository map for a given folder ID, showing important functions/classes and relationships. It is specific and actionable, though it does not explicitly distinguish itself from sibling tools like map_codebase or get_dependency_graph.

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 states a clear use case: get a high-level understanding of a Code Repository. It provides context for when to call the tool, but does not mention exclusions or alternatives, so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate those. It adds a meaningful behavioral detail: the underlying model is Qwen-Image-Edit when installed, else FLUX Kontext. This helps the agent anticipate variability in output quality or availability. It doesn't contradict the annotations. The only gap is no explicit statement about what the function returns, but that is not a contradiction.

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

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

The description is tight: three sentences. The core purpose is front-loaded, the model detail is secondary, and the sibling routing comes last. There is zero filler; every sentence adds distinct value. This is exemplary for a tool description.

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

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

For an image-editing tool with no output schema, the description covers purpose, model selection, and routing to alternatives. It does not explicitly state what the tool returns (presumably the edited image), but that is reasonably inferred. Given the clear purpose and the existence of sibling tools for related tasks, an agent has enough context to decide when and how to call this tool. Minor omission: no note on idempotency behavior, but that is documented in the parameter schema.

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

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

Schema description coverage is 100%, so every parameter (image, steps, instruction, idempotency_key) already has a description. The tool description itself does not add parameter-level detail beyond the schema; it only gives example instructions. Baseline 3 is appropriate when the schema carries the semantic load, and the description does not need to compensate.

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

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

The description opens with a specific verb-resource pair ('Change or remove something in an attached photo') and gives concrete examples ('remove the coffee cup', 'replace the sky with sunset'). It explicitly names sibling tools (outpaint_image, generate_identity) and what they do differently, so an agent can immediately tell this tool apart without inspecting schemas.

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

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

It provides explicit routing: 'For extending the canvas use outpaint_image. For a brand-new scene of a person's face use generate_identity.' This tells the agent when NOT to use this tool and names the alternatives, which is the strongest form of usage guidance. The examples also clarify the kind of instructions to supply.

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?

The readOnlyHint annotation already declares this as a safe read operation. The description adds useful behavioral context by stating it returns a formatted tree view of directory contents, which is not evident from the schema or annotations alone.

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

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

Two focused sentences convey the action, output format, and usage intent with no wasted words. The main purpose is front-loaded, making it easy for an agent to quickly understand the 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?

For a simple read-only list tool with fully documented parameters and no required arguments, the description is complete. It covers what the tool does, what it returns, and when to use it. The absence of an output schema is mitigated by the explicit 'formatted tree view' statement.

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

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

Input schema has 100% coverage, with directory and max_depth fully described including defaults. The description adds no new parameter details, but it also does not need to given the schema's completeness, so the baseline score of 3 is appropriate.

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

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

States a specific verb and resource ('List files and directories') and the output form ('formatted tree view'). It clearly differentiates from sibling tools like read_code, search_codebase, and list_code_repositories, which serve different purposes.

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 describes the intended use case: 'Use this to explore the codebase and find relevant files.' It provides clear context for when to invoke this tool, though it does not name alternatives or give exclusion criteria.

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

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

Annotations declare readOnlyHint=true, and the description adds useful behavioral context by noting that only folders with is_repository=True and analysis completed are returned. It also discloses the exact output fields: id, name, path, and repo_metadata availability, which goes beyond the annotation's safety hint.

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

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

The description is concise and front-loaded, beginning with the core listing behavior and output before moving to usage scenarios. The example phrases are helpful, though the description is slightly longer than strictly necessary and includes a minor typo ('guaardvark'), which keeps it from a perfect score.

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 list tool, the description provides everything needed: the filtering condition, the returned fields, the triggering user language, and the purpose of the returned folder ids. No output schema is present, so including the return fields is especially valuable. The description is complete for the tool's complexity.

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

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

The tool has zero parameters, so there are no parameter semantics to document. Per the baseline for zero-parameter tools, the description does not need to compensate for missing schema documentation, and it correctly focuses instead on what the tool returns and when to call it.

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

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

The description opens with a specific verb and resource: 'List all Code Repository folders', and clearly scopes the result to those 'marked as such (is_repository=True) and analyzed'. It also names downstream tools like get_repository_map, get_dependency_graph, and read_ast_node, which distinguishes this tool from sibling listing tools.

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

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

The description gives explicit context for when to use this tool: 'Use this first when the user refers to...' and offers concrete example phrases like 'the uploaded code'. It does not explicitly state when not to use it or compare it directly to a sibling like list_code_files, but the guidance is clear enough to route an agent correctly.

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 is consistent. It adds useful context about the current knowledge-base state, passage counts, and paging/filter support. No side effects or auth details need disclosure for a simple read-only listing.

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

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

Three sentences, each purposeful: the core action, the recommended use case, and supported options. Information is front-loaded and there is no redundancy.

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

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

For a simple read-only list tool with fully documented optional parameters and no output schema, the description gives enough to decide when to call it and what to expect (documents plus passage counts). The absence of exact return structure is a minor gap given the low complexity.

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

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

The input schema describes all three parameters with 100% coverage, so the baseline is 3. The description only recaps paging and name filtering without adding new parameter semantics or format 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?

Clearly identifies the verb (list), resource (documents in the knowledge base), and a distinguishing detail (per-document passage counts). This separates it from sibling search and read tools, so an agent can accurately select it without inspecting other 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?

Provides explicit usage context: 'Use this to find out what the knowledge base actually contains before searching it.' This makes the intended scenario clear, though it does not explicitly name alternatives or state when not to use it.

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

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

The readOnlyHint annotation already establishes the operation is safe. The description adds useful behavioral context: it runs the same snapshot as /system-map and returns specific output types. No contradictions with annotations are present.

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

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

A single sentence packs the core action, output, and usage triggers with no filler. It is appropriately concise and front-loaded.

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

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

Given the read-only annotation, fully described optional parameters, and explicit usage examples, the description covers the essential invocation context. It does not detail the exact structure of 'stats' or 'ranked findings', but that is not required for correct selection and invocation.

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

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

Schema description coverage is 100%, so each parameter (root, limit, refresh) is already documented in the schema. The description does not add extra parameter-level nuance, fitting the baseline of 3.

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

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

The description clearly states the specific action ('Run the System Mapper') and resource, and specifies the output ('stats plus ranked findings'). It also lists distinct trigger phrases that help separate it from sibling tools like analyze_code or 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?

The description gives explicit usage triggers: 'Use when the user says...' with concrete phrases. It does not mention when not to use it or name alternatives, but the trigger guidance is strong enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds no extra behavioral context such as effects on the current player, prerequisites (e.g., an active media session), or error behavior when no player is available. The action names imply mutation, but nothing beyond that is disclosed.

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

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

The description is two short sentences with zero filler. The main purpose is front-loaded first, and the action list follows immediately in a compact, scannable format. Every word contributes.

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

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

For a simple tool with 100% schema coverage and clear annotations, the description is mostly sufficient for basic invocation. The main gaps are absence of usage boundaries versus sibling media tools and no behavioral notes about player autodetection or failure modes, leaving the agent to infer edge-case behavior.

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

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

Schema coverage is 100%, but the description enriches the action parameter beyond the schema by clarifying the meanings: next means "skip to next track", previous means "go back", and toggle means "play/pause toggle". The player and idempotency_key parameters are already well documented in the schema, so the description adds meaningful value where needed.

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

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

The description gives a clear verb and resource: "Control media playback," then enumerates the specific actions (pause, stop, next, previous, toggle). This is unambiguous about what the tool does, though it does not explicitly differentiate itself from sibling tools like media_play, media_volume, or 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?

The action list strongly implies use for playback transport control (pause, skip, toggle) rather than volume or status queries. However, the description never explicitly says when to prefer this tool over media_play or media_status, so the guidance is implied rather than stated.

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

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden of behavioral disclosure. It states that VLC is launched and that playback resumes when no query is given, which are side effects. It does not mention potential interruption of current playback or error behavior, but for a play command, these are implied. The description adds meaningful context 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?

The description is three sentences, front-loading the core purpose and then covering usage patterns and the underlying mechanism. Every sentence earns its place without excessive detail. It could be slightly tighter (e.g., merging the VLC mention into the first sentence), but it remains efficient and readable.

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 four optional parameters and no output schema, the description covers the main scenarios (specific search, generic request, resume) and the underlying action (launching VLC). It does not explain what happens when no matching music is found or how directory interacts with query, but these are edge cases the schema partially addresses. Overall, an agent has enough to invoke the tool correctly in most cases.

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 repeats the key guidance for the query parameter (use 'music' for generic, omit to resume), which is already in the schema. It adds no new meaning for shuffle, directory, or idempotency_key, all of which are adequately described in the schema. Thus, the description provides marginal added value.

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

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

The description clearly states the tool plays music by searching for songs, artists, albums, or genres, which is a specific verb-resource pairing. It also distinguishes itself by explaining edge-case behaviors (generic 'play some music' and resume without query). While it doesn't explicitly name sibling tools, the focus on launching playback and the mention of VLC makes its role distinct from media_control (likely for pause/skip) and media_volume.

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

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

The description gives explicit guidance for generic requests (use query='music') and for resuming playback (omit query). It implies when to use this tool versus alternatives by its focus on starting playback, but it doesn't explicitly state 'use media_control for pause' or list exclusions. Still, the context is clear enough for an agent to select it correctly.

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 provide readOnlyHint=true, and the description reinforces a non-mutating read operation with no contradiction. It adds value by specifying the return contents (title, artist, album, player state, volume level), which is useful behavioral context beyond the schema. It does not discuss edge cases like no active player, but the read-only nature is well 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?

The description is one concise sentence with the core action front-loaded and the detailed contents following immediately. Every word contributes useful information, with no redundancy or filler.

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

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

For a simple read-only status tool, the description covers the main return areas and aligns with the optional player parameter and readOnlyHint. It is slightly thin on edge-case behavior (e.g., what happens if no player is active, or how auto-detection behaves), but given the tool's simplicity, the description is largely sufficient.

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

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

Schema description coverage is 100% for the single optional 'player' parameter, so the schema already documents it. The description does not add any additional semantics about the parameter, which fits the baseline of 3 for high schema coverage.

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

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

The description uses a specific verb-resource pair ('Get current playback status') and enumerates exactly what the tool reports: track info, player state, and volume level. It is clearly distinct from siblings like media_play, media_control, and media_volume, so an agent can identify it as the status-query tool without ambiguity.

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 implicitly tells the agent to use this when playback status is needed, rather than controlling or changing media. However, it does not explicitly state when not to use it or name alternative tools, so the usage guidance is inferred rather than stated.

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

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

Beyond annotations, the description discloses that the tool both reads and mutates system volume and enumerates accepted modes ('absolute', 'relative', 'mute', 'unmute'). The annotations already signal non-read-only and non-destructive behavior, so the description adds useful context without needing to restate everything.

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

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

Two tight sentences front-load the core operation and immediately provide concrete syntax examples. There is no filler or redundant explanation.

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

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

For a simple tool, the description covers operation, volume range, and accepted value formats; idempotency_key is fully documented in the schema. The only minor gap is that the return value for 'get' is not explicitly described, but it is reasonably inferable.

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 both parameters. The description largely restates the level parameter's allowed formats without adding new meaning, so the baseline 3 applies.

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

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

The description names a specific resource ('system audio volume level') and explicit verbs ('Get or set'), supported by a 0-100 scale. This clearly distinguishes media_volume from siblings like media_play, 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?

The intended use is clear: adjust or read system volume. It doesn't explicitly name alternatives or exclusions, but no sibling appears to handle volume, so this is sufficient context for selecting the tool.

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

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

Annotations are only non-readonly and non-destructive hints, which provide little safety detail. The description adds that new area should match the scene, but it does not disclose whether the original image is modified, whether the operation is asynchronous, cost/time implications, or what the output will be. There is no contradiction with annotations.

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

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

The description is very concise and front-loaded with the core action. Every sentence earns its place: purpose, usage trigger, and implementation preference. There is no filler or redundant repetition of schema data.

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 and a non-trivial image-generation tool, a sentence about what the tool returns or whether it runs asynchronously would round out the description. The full parameter schema, clear trigger phrases, and attached-image handling make the core operation understandable enough for an agent to invoke it.

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

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

The input schema already has 100% parameter description coverage, so top, left, right, bottom, steps, instruction, and idempotency_key are well-documented there. The description only adds the general notion of one or more directions and an attached photo, which does not materially clarify parameter behavior beyond the schema.

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

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

The description clearly states the tool expands an attached photo in one or more directions and fills the new area to match the scene. This distinguishes it from image-editing siblings like inpaint_image and edit_image, which address different modifications.

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

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

The description explicitly says to use the tool when the user says extend, expand the canvas, or outpaint, which gives clear invocation triggers. It does not name alternative sibling tools or provide exclusion criteria, but the guidance is sufficient for basic routing.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals key behavioral facts: it does NOT post, it scours target_url (including scraping YouTube metadata), and it places the result in a queue at status='drafted' for human approval. These are meaningful side-effect and workflow details that are not captured in the annotations or schema.

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

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

The description is compact and front-loaded, with the most important constraint ('does NOT post') in the first sentence. Mode-specific requirements and the approval flow are packed into three additional sentences with 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 10-parameter tool with no output schema, the description covers platform scope, mode constraints, required inputs, defaults, scraping behavior, and post-draft workflow. The only notable gap is that it does not describe the return value shape, which the absence of an output schema leaves to the agent to infer. Otherwise it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining mutually exclusive parameter requirements (thread_context vs target_url for comment mode), defaults for share_link, and mode-specific semantics for share_target and include_link. It does not enumerate every parameter, but the schema already handles those.

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

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

The description opens with a specific verb and resource: 'Draft a social outreach comment or share post (does NOT post).' It lists the exact platforms and immediately contrasts with post/publish operations, making the tool's boundary clear. This distinguishes it from siblings like request_publish and outreach_reject_draft without needing to inspect 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 mode-based conditions: comment mode requires thread_context or target_url, while share mode requires share_target and optionally share_link. It also states the draft awaits human approval, clarifying when the tool is appropriate. It does not explicitly name sibling alternatives like request_publish for posting, so a small inference is left to the agent.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description reinforces this by saying it lists drafts. It adds useful behavioral context: default status is 'drafted', status values mean different pipeline stages, and results are limited by `limit`. This exceeds the minimal safety signal from 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?

Three sentences, each earning its place: the core action, the status semantics, and the limit behavior. The most important information is front-loaded, and there is no filler or repetition of schema content.

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

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

For a simple read-only list tool with two well-documented parameters, the description covers the essential invocation details: defaults, status meanings, and row limits. It does not mention ordering, but this is a minor omission given the tool's simplicity and the absence of an output schema to clarify further.

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

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

The input schema already covers both parameters thoroughly (100% coverage), so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining what each status represents in the workflow (pending review, queued to post, recent history) and clarifying that `limit` caps returned rows. This adds value without being redundant.

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

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

The description states a specific action ('List') and resource ('social outreach drafts') and clarifies the meaning of each status filter. It clearly distinguishes this tool from mutation-oriented siblings like outreach_draft_post, outreach_reject_draft, and request_publish by framing it as a read-only listing operation.

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 concrete usage context per status: 'drafted' means pending review, 'approved' is queued to post, 'posted' is history. It stops short of explicitly naming when to prefer this over sibling tools like outreach_status, but the status-based usage guidance is strong enough for an agent to select and invoke it correctly.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description adds useful context beyond that: the row is marked 'rejected' and will not post. This clarifies the actual state change without contradicting the annotations.

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

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

Two short sentences deliver the action, the effect, and the user-intent triggers without any filler. The core behavior is front-loaded, and the examples are compact yet helpful.

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 mutation tool with annotations and full schema coverage, the description is complete: it names the operation, the target, the resulting state, and the language users might use to request it. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents both id and idempotency_key. The description only reinforces that the id identifies the draft; it adds no new parameter-level meaning.

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

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

The description states a specific verb ('Reject'), a specific resource ('an outreach draft'), and the precise effect ('Marks the row 'rejected' so it won't post'). This clearly distinguishes it from posting tools like outreach_draft_post and from read-only outreach tools.

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

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

The description explicitly gives when to use the tool with natural-language examples like 'kill that one' and 'don't post draft 42'. It does not explicitly mention alternatives or when not to use it, but the usage trigger is concrete and unambiguous.

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

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

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?

The readOnlyHint annotation already signals the tool is non-mutating, and the description's 'extract content' wording is consistent with that. The description adds file-format context, but it does not disclose output format, behavior on unsupported files, size limits, or any other operational traits beyond what the annotation and basic action imply.

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

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

The description is a single concise sentence with no filler. It front-loads the action and resource, then enumerates supported formats. Every word earns its place, and 'etc.' adequately signals the format list is non-exhaustive.

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 should explain what the tool returns or yields after processing, but it only says 'extract content,' leaving the result format ambiguous. There is also no mention of error cases or how to handle unsupported file types, so an agent is left guessing about the call's outcome.

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

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

Schema description coverage is 100% for file_path, so the schema already documents the only parameter. The description adds meaning by listing supported file types, which gives the agent a sense of acceptable input values, but it does not elaborate on path syntax, relative vs. absolute paths, or any additional constraints.

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 clear action ('extract content') on a resource ('files') and lists common formats (PDF, DOCX, CSV, images, Excel), which helps identify what the tool handles. However, the verb 'process' is generic, and it does not explicitly distinguish this tool from sibling file-readers like read_code or analyze_code, so it is not fully differentiated.

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

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

The description gives no guidance on when to use this tool vs. alternatives. Sibling tools such as read_code, analyze_code, and read_logs overlap in the general 'read/process a file' space, and no conditions or exclusions are provided to help an agent choose correctly.

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 adds useful behavioral context: it extracts exact source verbatim, currently supports only Python files, and requires a repository-relative path. It could mention error behavior or return format, but given the read-only annotation and simple operation, the added detail is sufficient.

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

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

The description is two tight sentences with no wasted words. The first sentence identifies the action and object; the second adds key differentiators and constraints. Every sentence earns its place.

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

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

For a simple read-only tool with all required parameters documented in the schema, the description supplies the purpose, constraints, and differentiators. 'Read the exact source code' implies the return value is the source snippet itself. The only minor gap is the absence of explicit error-case behavior, so it stops short of a perfect 5.

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

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

Schema description coverage is 100%, with inline descriptions for filepath, folder_id, and node_name. The tool description reinforces the roles of filepath and node_name but does not add new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a clear verb ('Read'), a precise resource ('exact source code of a specific class or function from a Python file'), and a clear scope ('Code Repository folder'). The token-efficiency contrast differentiates it from reading whole files, which is especially relevant given sibling read tools like read_code and process_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?

It explicitly says when to use this tool: when you need precise, token-efficient extraction of a specific class or function rather than the entire file. It also provides constraints—Python-only and repository-relative filepath. It does not name specific sibling tools, but the guidance is clear enough for an agent to decide appropriately.

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

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

The readOnlyHint annotation already marks the tool as read-only. The description adds value by specifying the return includes line and character counts, and by clarifying path semantics (relative vs absolute for external files). No side effects or contradictions are present.

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

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

Three dense, front-loaded sentences: action, return value, usage context, and path rules. Every sentence earns its place with no redundancy or filler.

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

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

For a one-parameter, read-only tool with no output schema, the description provides purpose, usage context, return information (line count, character count), and path handling. An agent has enough to select and invoke the tool correctly without additional lookups.

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 largely repeats the path rule already in the schema ('relative to project root' vs 'absolute path for external text file'). It adds no meaningful new parameter semantics beyond the schema.

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

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

The description starts with a specific verb and resource: 'Read the complete contents of a source code file.' It clearly differentiates from siblings such as read_logs (logs), search_code (search), and list_code_files (list). Including the return value (line count, character count) further sharpens the tool's identity.

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 this to understand existing code before making modifications' provides a clear, actionable when-to-use context. The description does not explicitly mention alternatives or when-not-to-use, but for a simple read tool, this is sufficient guidance.

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

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

The readOnlyHint annotation already covers safety, so the description's job is to add context. It adds that the tool reads 'actual indexed text' and mentions the usage flow with get_document_outline. It does not describe behavior when no page_label or heading_path is provided, or error cases, but given the annotation covers read-only, a 3 is appropriate.

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 with no redundancy. The main action is front-loaded, and the usage context is given in a single subordinate clause. Every word earns its place.

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

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

The description is complete for a simple read tool: it states what it reads, when to use it, and its relationship to get_document_outline. It lacks clarification on behavior when neither page_label nor heading_path is supplied, which could lead to ambiguity, but the core use case is well-covered.

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

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

Schema coverage is 100%, so all three parameters are already described in the input schema. The description repeats the heading_path source (from get_document_outline) but does not add new meaning beyond that. The baseline for full coverage is 3, and the description adds minimal extra value.

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

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

The description clearly states the tool reads indexed text of a section or page, specifying the verb (read) and resource (section/page of a document). It also differentiates from searching by explicitly saying 'without searching' and mentions the prerequisite tool get_document_outline, making it distinguishable from siblings.

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

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

It provides explicit guidance on when to use: after get_document_outline when you know the part you need. It also excludes searching, which helps agents avoid search tools. However, it does not name specific search alternatives (like search_knowledge_base or search_codebase) explicitly, but the 'without searching' exclusion is clear enough.

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

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

The annotation readOnlyHint=true already declares the operation is safe and non-mutating, and the description adds genuine value by disclosing the 'tail' semantics (reads the trailing portion) and the logs/ location. However, it does not disclose the return format or pagination/truncation behavior, leaving some behavioral detail unspecified.

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

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

Two sentences with zero waste. The core action is front-loaded in the first sentence, and the second adds high-value usage triggers. Every word earns its place.

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

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

For a read-only tail tool with 0 required params, full schema coverage, and a readOnlyHint annotation, the description covers purpose, location, and when to use it. The only gap is return format, which is minor for a simple log-tail operation and not covered by an output schema.

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

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

Schema description coverage is 100% — all three parameters (name, lines, query) are documented in the schema with defaults and constraints. The description adds no parameter-level detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb ('Tail') plus a concrete resource and scope ('a Guaardvark log file under logs/'). The trigger-phrase examples ('review the logs', 'check backend.log') sharpen what this tool is for and clearly distinguish it from read-code/document siblings that operate on source files rather than logs.

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 guidance via natural-language trigger phrases ('review the logs', 'celery errors', 'what did the last crash say'). It does not name an alternative tool or state when not to use it, but among the siblings there is no competing log reader, so the omission is minor.

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

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

The description adds behavioral details beyond the annotations: the result is a transparent PNG, the tool does not invent a new scene, and the attached image is used automatically when image is omitted. It could further disclose whether the original file is modified or whether processing is synchronous, but the core behavior is clear.

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

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

Three short sentences front-load the action and output format. The first two sentences are essential; the third repeats schema content but is brief and reinforces the common calling pattern, so the redundancy is mild.

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

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

For a two-optional-parameter tool with no output schema, the description covers what the tool does, the output format, the intended use cases, the alternative tools, and the default input behavior. No critical operational detail 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 description coverage is 100%, so the schema already documents both image and idempotency_key. The description restates the auto-use of the attached image, which is already present in the schema's image property ('Usually omit — the attached image is used'), so it adds little beyond the structured definition.

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

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

The description names a specific verb and resource: 'Remove the background from an attached photo and return a transparent PNG.' It also distinguishes the tool from sibling image-manipulation tools by explicitly disclaiming scene invention and naming generate_identity/edit_image as the alternatives for that need.

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

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

The phrase 'Use for product shots, stickers, and cut-outs' states the intended application, and 'Does not invent a new scene — use generate_identity or edit_image for that' gives an explicit when-not-to-use rule with named alternatives. This routes an agent correctly without needing to inspect siblings.

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

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

The description discloses the most important behavioral trait beyond annotations: 'This does NOT post: the request waits on the Approvals page until a person approves, rejects or cancels it, whatever the publish settings say.' This async, approval-gated behavior is essential context that annotations (readOnlyHint=false, destructiveHint=false) do not convey. No contradiction with annotations.

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

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

Three tightly written sentences with zero filler. The most decision-relevant facts are front-loaded: the non-posting caveat appears immediately after the purpose, before any parameter guidance.

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?

Complete for a request tool: purpose, approval behavior, and parameter usage are all covered. With no output schema, the rule exempts return-value explanation. A minor gap is that it doesn't mention how to check the outcome of an approval, but the Approvals-page reference suffices.

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 documents all five parameters. The description adds real value on the connection parameter by explaining when to omit it and what values to pass (id or name), going slightly beyond the schema's 'Optional when only one exists.'

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

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

States a specific verb-resource pair ('Ask to publish a text post to one of the user's social connections') and enumerates the exact target platforms (Discord webhook, Bluesky, Mastodon, Telegram). The critical qualifier that it 'does NOT post' immediately separates it from a direct-publish tool, and it stands apart from the content-generation siblings.

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

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

Explains the approval workflow clearly and gives concrete parameter guidance ('Omit connection when only one is set up; otherwise pass its id or name'). It does not name alternative tools explicitly, but for a publish-request tool the key usage context (waits for human approval) is 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 already indicate write (readOnly=false) and non-destructive behavior. The description goes further by stating data is persisted to long-term memory and can influence future behavior, which is useful context beyond the annotation flags.

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

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

Two concise sentences front-load the core action and follow with concrete usage context. Every sentence earns its place with no filler.

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

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

For a 5-parameter write tool with no output schema and no nested objects, the description provides sufficient purpose and usage guidance. Parameter details are fully covered by the schema, and the annotation set covers safety behavior.

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 reinforces what content to store but does not add significant meaning beyond the schema's own parameter descriptions.

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

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

The description states a specific verb ('Save') and resource ('long-term memory') and enumerates what can be saved: facts, user preferences, or instructions. It is clearly distinct from retrieval-focused siblings like search_memory 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?

It explicitly says to use this when the user tells you things about themselves, their projects, or desired behavior, which gives clear when-to-use context. It does not name alternative retrieval tools or exclusions, but the sibling set makes the intended use obvious.

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 useful behavioral details beyond that, such as case-insensitive regex matching and the exact shape of results (file paths, line numbers, matched content). It is consistent with the read-only annotation and provides meaningful context without contradiction.

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

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

Two sentences convey the operation, regex behavior, return contents, and a guiding use case with no redundant or filler language. The most decision-relevant detail is front-loaded.

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

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

For a simple, read-only two-parameter search tool with no output schema, the description covers key runtime behavior: regex matching, result contents, and search scope. It omits minor details like regex flavor or default file glob, but those are already listed in the schema.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters with examples and defaults. The description reinforces that the pattern is regex-based but does not add meaningful parameter semantics beyond what the schema provides, so a baseline 3 is appropriate.

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

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

The description clearly states the tool searches for code patterns using case-insensitive regex and returns file paths, line numbers, and matched content. It is specific about the resource (code) and the operation (search), though it does not explicitly distinguish itself from the similarly named sibling search_codebase.

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

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

The final sentence gives a clear intended use ('Use this to find where code patterns exist before making changes'). It does not mention when not to use it or explicitly name alternatives, so it falls just short of the strongest guidance.

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

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

Annotations only provide readOnlyHint: true. The description adds valuable behavioral context beyond that: the codebase is already indexed, no path or upload is needed, it supports meaning- or symbol-based queries, and it returns files with line numbers and code. This meaningfully expands on the safety trait.

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?

Four sentences with no wasted words: purpose and key trait first, then examples, then return format, then usage guidance. Every sentence earns its place and the most important information is front-loaded.

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

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

No output schema exists, but the description covers the return shape (files with line numbers and code), the indexing/setup-free behavior, and typical usage patterns. It is nearly complete, with the only gap being explicit disambiguation from siblings like 'search_code or read_code.

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 'Ask by meaning or by symbol' but this essentially restates the query parameter's schema description ('What to find, in plain words or as a symbol name'). It doesn't add new parameter-level meaning, so a 3 is appropriate.

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

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

The description states a specific verb and resource: 'Search the current project's source code' and gives concrete examples of query types, such as 'where it is decided whether a model supports thinking' and 'callers of think_payload'. The scope is clear, but it doesn't explicitly differentiate itself from the similarly named sibling 'search_code', so it falls just short of a 5.

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

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

The description gives explicit usage context: 'Use it before saying the code is unavailable, before reading whole files, and instead of shell commands like grep or ls.' This clearly tells an agent when to prefer this tool, though it doesn't name sibling alternatives or explicitly state when not to use it.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds valuable behavioral detail beyond that: results are verbatim source passages with filenames and relevance scores, not a synthesized summary, and the agent should cite filenames in answers.

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

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

The description is two sentences with no filler. It front-loads the action and scope, then immediately states the output format and citation instruction. Every sentence earns its place.

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

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

For a read-only search tool with a fully documented schema and no output schema, the description adequately explains what the agent will receive back (passages, filenames, relevance scores). It could be marginally more complete by routing between sibling search tools, but the core call and return behavior are sufficiently covered.

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

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

The input schema has 100% description coverage, documenting query, top_k, project_id, and filter_type with meaningful detail including ranges and real filter values. The description does not add parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states a specific verb ('Search'), a clear resource ('internal knowledge base'), and the kinds of information it covers ('project, architecture, code repositories, or documents'). It also distinguishes itself from sibling code/memory search tools by specifying verbatim passages with filenames and relevance scores, and explicitly notes it is not a summary.

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

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

The description gives clear context about when to use it: when searching the internal knowledge base for project, architecture, repository, or document information. It does not explicitly name sibling alternatives or state when not to use this tool, but the intended scope is reasonably 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 aligns with that by framing the operation as a search. The description adds the semantic scope ('long-term memory', 'previously saved facts, preferences, or instructions') but does not disclose behavior beyond that, such as result ordering or relevance mechanics.

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, front-loaded sentence that states the action, the resource, and the content scope without any filler. Every word contributes to the agent's understanding.

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, read-only, two-parameter search tool, the description is sufficient: the agent knows what to search, what type of content will be returned, and that the operation is safe. Return format is not described, but for a memory retrieval tool this is reasonably inferable and annotations cover the safety profile.

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

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

Schema description coverage is 100%, so both 'query' and 'limit' are already documented in the schema. The description adds no additional parameter detail beyond what the schema provides, so the baseline of 3 is appropriate.

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