Vilix AI

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

Beyond the idempotentHint annotation, the description discloses meaningful behavior: urgent messages are redelivered on every read until acked or expired, and re-acking returns already_acked: true. It also implies a mutation is performed while being safe, consistent with 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?

Three sentences, each providing essential information: when to ack, why urgent acks matter, and the idempotent behavior. The main action is front-loaded, and there is no filler.

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

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

For a single-parameter acknowledgement tool, the description is complete: it covers purpose, timing, urgency requirements, redelivery behavior, and idempotency. The output schema can handle return-value expectations, so nothing critical is missing.

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

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

The single required parameter message_id has 0% schema description coverage, but the description compensates by telling the agent to 'pass the item's id.' This clarifies that message_id refers to the inbox message's identifier. It does not say where to obtain the id, but for one parameter this is enough context.

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: 'Acknowledge an inbox message after you have read and handled it.' It clearly explains the action and what object it applies to. The tool's purpose is distinct from all listed siblings, so an agent can identify it 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 gives clear usage timing: acknowledge only after reading and handling the message. It also explains that urgent messages require acknowledgement and will be redelivered otherwise. It does not explicitly name alternatives or when-not-to-use cases, but the context is sufficient for this simple 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 only provide false hints, so the description carries the behavioral burden. It discloses a consequential trait: the rule is injected only on every NEW chat, not existing chats. It also provides useful limits (15000 chars, max 20 rules per user), though it does not describe edge-case behavior at those limits.

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 with the core behavior stated first, followed by examples and constraints. No filler or redundant content 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 one-parameter creation tool, the description covers purpose, content format, limits, and effect on future chats. An output schema exists, so return-value documentation is not needed. A pointer to update or remove alternatives would make it 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?

The schema only names the 'text' parameter as a string with no description. The description fully compensates by defining text as freeform directives, offering concrete examples, and specifying the max length. This adds substantial meaning 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 uses the verb 'Add' and the resource 'personal user_rule', and clarifies the effect: injected on every NEW chat. It also distinguishes from sibling tools by signaling creation of a personal rule rather than listing, updating, or removing rules.

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 conveys the intended use case—creating a new personal rule with freeform directives—but does not explicitly say when to choose this over update_user_rule or remove_user_rule. No alternative tools are named. Usage is implied rather than explicitly routed.

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 this is mutating and not idempotent, so the description need not restate that. It adds useful context about how project_rules propagates to tasks, but it does not disclose persistence effects, error conditions, or any side effects beyond creation. This is acceptable for a simple create tool but not richly transparent.

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

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

Three brief sentences with no filler. The main action is front-loaded, and each subsequent sentence addresses one of the two optional parameters. Every clause contributes meaning.

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 creation tool with three parameters and an output schema present, the description covers the required and optional parameters adequately. It lacks an explicit pointer to update_project for existing projects, but that is a usage distinction rather than a missing operational detail needed to invoke this tool correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden. It compensates well: title is marked as required, description is explained as a one-line goal, and project_rules is given concrete meaning as markdown covering stack/conventions/tone inherited by tasks. It does not elaborate on nullability or format constraints, but the schema already displays defaults.

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 'Create a new project,' naming an explicit action and resource. It is distinct from sibling tools like create_task and update_project by clearly targeting project creation, and the following sentences specify what counts as a project (goal plus inherited rules).

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 word 'new' implies this is for creation rather than updates, and the note that project_rules is inherited by tasks suggests when project-level context is needed. However, no alternative tools are named and no explicit when-not-to-use guidance is given, so selection among siblings is largely left to inference.

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

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

Annotations already mark this as a non-read, non-idempotent write, and the description adds valuable behavior beyond that: suggest and confirm before saving, don't create duplicates by checking list_skills, and the per-plan skill cap. It doesn't cover auth or rate limits, but those are not strongly implied by 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 dense but organized: purpose first, then usage policy, then parameter semantics, then scoping. It is longer than strictly necessary, but each sentence adds decision-relevant information rather than padding.

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

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

For a five-parameter creation tool with no schema descriptions, the description covers purpose, when to use it, how to avoid duplication, parameter meaning, scoping, and plan limits. The only material omission is the enabled parameter, and the existence of an output schema means return-value explanation is not required.

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

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

With 0% schema description coverage, the description carries the full explanatory burden and does so for name, description, body, and project_id, including the indexing and lazy-loading behavior. The only gap is the 'enabled' parameter, whose meaning is left entirely to inference.

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

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

Opens with a specific verb and resource ('Save a reusable Agent Skill') and defines it as a how-to procedure for a recurring task, with a concrete example. It also orients the agent against sibling tools by referencing list_skills for duplicates and get_skill for body loading.

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 trigger conditions: offer to save after a non-trivial procedure, confirm first, avoid silent or trivial saves, and call list_skills before creating. It also explains global vs project scoping, which is exactly the decision an agent needs to make before invoking.

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 a non-read-only, non-destructive operation, and the description adds that the operation creates a task scoped to a project. It does not mention return behavior, permissions, failure outcomes, or task state, so it stops short of full transparency.

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

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

Two short, front-loaded sentences deliver the main action, project scope, and the two non-obvious parameters without filler. Every phrase 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 straightforward create call with an output schema and annotations, the description plus input schema is sufficient to invoke it correctly: required project_id and title, optional priority and body. Minor gaps are explicit alternative routing and initial task state, but these are not required to make the call.

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

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

With 0% schema description coverage, the description compensates by documenting priority's allowed values and default, and by explaining that body is markdown for goals, notes, and constraints. It also clarifies project_id's role through 'inside a project'; title is self-evident from its name.

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

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

The description states a specific action and resource: 'Create a task inside a project.' This clearly separates it from create_project/create_skill by resource and from update_task/update_task_state/delete_task by 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?

No guidance is given about when to use create_task versus update_task or update_task_state. The description only states the action, leaving the agent to infer routing from sibling tool names.

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 destructiveHint=true and readOnlyHint=false. The description adds the important cascade consequence and the explicit-consent guardrail, which go beyond the structured annotations. No contradiction exists.

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 front-loads the most important warning ('Destructive'), states the core behavior, and adds the invocation condition. There is no filler or redundant restatement of the schema.

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

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

For a one-parameter tool with an output schema, annotations covering safety, and a clear usage rule, the description is complete. It specifies the cascade behavior and the explicit-deletion requirement, which are the only contextual details an agent needs beyond the structured fields.

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

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

The description does not address project_id, and schema description coverage is 0%. However, the parameter is self-explanatory from its name and schema title ('Project Id'), and the tool has only one parameter, so the lack of elaboration has minimal practical impact.

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 ('deletes a project') and the resource, adding the critical detail that it cascades to tasks. This distinguishes it from sibling tools like delete_skill and delete_task, and the destructive prefix reinforces the operation type.

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 'Only call when the user explicitly asks to delete,' which gives a clear condition for use. It does not enumerate alternatives for deleting a single task, but the project-vs-task resource distinction is evident from the description and sibling list.

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

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

Annotations already declare destructiveHint and idempotentHint, so the description's leading 'Destructive' is redundant. It adds a useful user-consent condition and names the destroyed resource, but does not disclose consequences like irreversibility or related data effects. 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?

Two short sentences with the key warning front-loaded and zero filler. Every clause adds either action, condition, or 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?

For a one-parameter destructive tool, the description plus annotations and output schema cover the important cases: what it deletes and when it is permitted. It could mention how to obtain skill_id, but the sibling get_skill/list_skills and the obvious parameter name make this a minor gap.

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

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

The schema provides no description for skill_id (0% coverage), and the description does not explain where the ID comes from, its format, or that it must reference an existing skill. The mapping is only implicit through the phrase 'deletes a skill.'

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 action ('deletes a skill') and the resource, distinguishing it from sibling delete_task/delete_project and update_skill. The verb is specific and 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?

Provides an explicit gate: only call when the user explicitly asks to delete or remove a skill. This tells the agent exactly when to invoke the tool and implicitly warns against inferring intent.

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 destructive nature is covered by structured metadata. The description reinforces that and adds an important invocation guardrail ('only call when the user explicitly asks to delete'), but it does not disclose additional behavioral details such as what happens with a non-existent task_id. This is acceptable given the annotations and idempotentHint=true.

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 destructive warning and the core action are front-loaded, and the usage restriction is stated immediately afterward.

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 destructive operation, the description covers the essential safety rule and the action. With output schema and annotations present, it does not need to describe return values or safety hints. A minor gap is the lack of any guidance on task_id semantics or error behavior when the task does not exist.

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

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

Schema description coverage is 0%, and the description does not explain task_id at all. The property name is self-explanatory enough to avoid a score of 1, but the description fails to compensate for the missing schema documentation, so an agent must infer the meaning and format of task_id from its name alone.

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

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

The description states the exact verb 'deletes' and resource 'task', making the operation unambiguous. It also distinguishes the tool from non-destructive task-related siblings like create_task and update_task by explicitly flagging it as destructive.

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 an explicit condition for use: only call when the user explicitly asks to delete. It clearly implies not to call this tool in other situations, though it does not name alternative tools such as update_task_state or create_task as fallbacks.

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

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

Annotations already declare readOnly/idempotent behavior, and the description adds substantial context: internal relevance retrieval, ISO-timestamp conflict resolution with 'NEWEST timestamp is the latest known value,' the `also_related` payload quirk, and the always-returned `recent_messages` / `related_conversations` bridge. 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 long but each paragraph has a distinct job: core action, usage, timestamp behavior, then parameter details. Every sentence adds actionable information, param names are code-formatted, and the most important operational instruction ('Call this before you compose your reply') 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?

Despite no per-property schema descriptions, the description is complete for correct invocation: when to call, what to pass, what is returned, how to resolve timestamp conflicts, how to handle attachments, and cross-tool consistency with `save_turn`. The output schema exists, so detailed return-value enumeration is unnecessary.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining each parameter: `user_prompt` ('Pass the user's latest prompt only'), `chat_id` (null for new chats vs. from `save_turn` to skip re-injection), and `attachment_context` (optional summary, default '', pass same to `save_turn`). Every parameter is meaningfully documented beyond the bare 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 a specific verb and resource: 'Load the last few recent messages and semantically related past turns.' It also names the sibling tools (`search_semantic` / `search_keyword` / `recent_messages`) as alternatives, clearly positioning this tool as the default context loader rather than a targeted 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?

Usage guidance is explicit: 'Call this before you compose your reply' and 'Pass the user's latest prompt only.' It also provides conditions for alternatives with an example ('when the user names a source like ChatGPT'), plus chat_id guidance for new versus existing conversations.

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

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

Annotations already cover readOnly, idempotent, openWorld, and destructive hints. The description adds a meaningful behavioral detail beyond those annotations: tasks are returned ordered by priority desc then updated_at desc. It does not mention not-found behavior, but the low complexity and output schema reduce that need.

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 tight sentence that front-loads the purpose and tucks the ordering rule into a parenthetical. Every word earns its place and there is no filler.

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

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

For a one-parameter, read-only getter with full safety annotations and an output schema, the description is complete enough. It states the primary return content and the ordering behavior, so an agent has sufficient information 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 0%, and the single project_id parameter has no description in the schema. The description only says 'a project's' and does not explain where the ID comes from, its format, or any constraints, so it fails to compensate for the schema gap.

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

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

The description clearly states a specific verb ('Get'), resource ('a project's full state'), and scope ('including its tasks') with an explicit ordering rule. This unambiguously distinguishes it from list_projects and other get_* 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?

No explicit when-to-use or when-not-to-use guidance is provided, nor are any alternative sibling tools named. The intended usage is only implied by 'full state' versus list-style siblings, which is adequate but not directive.

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 key behaviors beyond the annotations: it returns a block the user pastes into settings, explains the `recommended` and `blocks` output structure, notes the tool-label matching behavior for `source`, and explicitly states 'it is not auto-applied' and 'Vilix logs nothing silently.' This aligns with and enriches the readOnly, idempotent, and non-destructive 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 detailed but every sentence serves a purpose: trigger conditions, return-value structure, parameter semantics, and opt-in behavior. It is front-loaded with the most important usage signal and uses structured mentions of `recommended`, `blocks`, and `source` to keep the information navigable.

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

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

Given the tool has one optional parameter, a rich output schema, and annotations covering safety, the description is complete. It explains what the tool returns, how the optional parameter affects the result, where the user should paste the result, and the opt-in nature, leaving no critical gap for an agent deciding 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 schema only defines `source` as string/null with a default, but the description fully explains its meaning and effect: the tool label the caller runs in, used to pick the right block, with examples and an omit-for-generic-default behavior. This fully compensates for the 0% schema description 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 opens with a clear purpose statement, 'Make Vilix automatic,' and then defines exactly what the tool returns: a custom-instructions block plus where to paste it. It gives explicit trigger phrases and clearly distinguishes this from sibling tools, which perform operations rather than setup guidance.

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 to call the tool: when the user asks 'how do I make this automatic' or 'set this up so it remembers on its own', or right after a first connection when offering setup. It also clarifies that this is an opt-in setup handoff, not something auto-applied, providing clear usage boundaries.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds useful behavioral context by clarifying the tool returns the full procedure body and should be treated as an instruction source rather than a reference lookup. It does not disclose error behavior, but the output schema mitigates the need for return-detail disclosure.

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

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

Two short sentences: the first states the core operation, the second gives the key usage rule. No filler or repetition, and the most important 'full procedure' and 'before doing the work' signals are front-loaded.

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

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

For a single-parameter, read-only retrieval tool with an output schema, the description covers the operational contract: what it loads, how to address the skill, when to call it, and how to use the result. Nothing critical is 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?

The schema only provides a bare 'ref' property with no description, and schema description coverage is 0%. The description compensates fully by specifying that ref is a skill name or id, which is exactly the semantic information an agent needs to populate this single required parameter.

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 ('Load one skill's FULL procedure (body)') and distinguishes it from list/index tools by emphasizing it returns the complete procedure, not just a skill listing. It also names the skill resource and accepted lookup keys ('name or id'), making the tool's role 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 gives an explicit when-to-use rule: call it when the request matches a skill shown in get_context or list_skills, and do so BEFORE doing the work. This is strong routing guidance that also explains why ('follow the returned body instead of improvising').

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

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

Annotations already cover read-only, idempotent, non-destructive, so the description doesn't need to restate those. It adds useful behavior: the returned text is written to be read aloud, relay it to the user; returns chat-sized answers plus structured fields for a guide-card UI; and the 'viewed' parameter logs downstream interactions. This adds meaningful context beyond annotations, so a 4 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 dense and well-organized: a lead sentence about when to call, a paragraph on what it returns, then one line per parameter. Every sentence earns its place, and the most decision-critical guidance is front-loaded. Despite length, it remains scannable and focused.

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

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

Given a low-complexity, zero-required-param tool with an output schema, the description covers when to use it, how to use the result, and all parameter details. It even anticipates the follow-up ('how do I make this automatic') and routes to the correct sibling. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry the full parameter documentation, and it does. It explains topic with all accepted enum-like values and what each means, tool to scope connect/asset links, and viewed with the valid values ('asset_viewed', 'custom_instructions_copied') plus when to omit it. This fully compensates for the missing schema descriptions.

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

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

The description states a specific verb ('get help'), the resource (Vilix guide), and the exact user intents it covers: what Vilix is, how to connect a tool, day-to-day use, and the discount/creator offer. It clearly distinguishes itself from the sibling get_setup_instructions by naming it and explaining the difference.

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

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

Explicitly says 'Call this when the user asks...' and lists concrete triggers. It provides a when-not/alternative by directing the user to get_setup_instructions for exact paste-in blocks and says the agent should prefer this help over sending the user to a website. This is exemplary usage guidance.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds minor behavioral context: the scope is limited to 'the user's projects' and the status filter. It does not disclose pagination, sorting, or other behavior, but for a simple read-only listing this is acceptable.

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 crisp sentences. The primary purpose is front-loaded, and the filter detail is delivered in a compact clause. There is no filler, redundancy, or irrelevant 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?

The tool is simple: one optional parameter, no required arguments, an output schema that documents return values, and annotations that cover side effects. The description covers the listing behavior and filter options, which is everything an agent needs to invoke this tool correctly. Nothing critical is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by documenting the only parameter: `status` is optional and restricted to active | paused | done. This adds meaningful value beyond the raw string/null schema and fully equips an agent to call the tool correctly.

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 ('List') and resource ('the user's projects'), making the tool's purpose immediately obvious. It also states the optional status filter, and the resource distinguishes it from list_skills, list_user_rules, and the project mutation tools.

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

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

The description provides clear context: use this tool to list projects, optionally filtered by status. It does not explicitly name alternatives or state when not to use it, but the purpose is straightforward enough that an agent can infer when to call it. The absence of explicit exclusions keeps it below a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value beyond them by explaining that include_disabled defaults to true and that only metadata is returned. It also clarifies that project_id scopes results to one project. 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 front-loaded with the core purpose, then adds workflow guidance, parameter details, and a clear pointer to get_skill. Every sentence contributes useful information without redundancy.

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

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

Given the tool's simplicity, two optional parameters, strong annotations, and an output schema, the description covers everything an agent needs. It even explains the broader skills-first workflow, making it more complete than expected.

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

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

Schema description coverage is 0%, so the description bears the burden of explaining parameters. It provides meaningful semantics for both: project_id filters to one project's skills, and include_disabled defaults to true. This is sufficient for an agent to understand each parameter's role, though it could be slightly more explicit about the effect of setting include_disabled to false.

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 ('List') and resource ('the user's saved skills') and enumerates the returned fields: name, description, scope, enabled. It also distinguishes itself from get_skill by noting it returns metadata only and that the full body is available via get_skill.

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

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

The description gives explicit when-to-use guidance: before a non-trivial or multi-step task, call this first to check for a saved procedure. It also names the alternative tool (get_skill) and the follow-up action, making the decision path very 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the useful behavioral detail that results are returned in 'display order', which is not present in the annotations. No contradiction exists.

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, tight sentence with no filler. It front-loads the action and resource and includes the only additional behavioral detail worth mentioning ('display order'). 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 zero-parameter, read-only listing tool with an output schema and clear annotations, the description supplies the core semantic details: what is listed, whose rules are listed, and the ordering. Nothing essential is missing for an agent to call this correctly.

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

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

The tool accepts zero parameters, so there is no parameter burden for the description to carry. The description does not need to add parameter-level meaning because there are none. The baseline of 4 for zero-parameter tools is appropriate.

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

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

The description uses a specific verb ('List') and a clear resource ('the user's user_rules'), and adds the scope qualifier 'the user's' plus ordering ('in display order'). This cleanly distinguishes it from sibling write tools like add_user_rule, update_user_rule, and remove_user_rule.

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

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

Usage context is implied rather than explicit: the tool is clearly the read/listing counterpart to the user_rule mutation tools, but the description never states when to prefer it over alternatives. An agent can infer the use case, but no direct guidance or exclusions are provided.

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 indicate only non-read non-destructive behavior (readOnlyHint=false), but the description goes well beyond that: it discloses redelivery semantics for 'urgent', the default delivery once per chat, expiry range, global unexpired limit, and that messages ride the next matching read call. This is rich behavioral context that an agent needs to call the tool correctly without side-effect surprises.

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 packed with necessary detail and is organized from the core action to delivery mechanism to parameter specs, all front-loaded with the most important purpose. Each sentence earns its place. Minor deduction: it reads slightly dense and could benefit from very light formatting separation, but this is still strong and efficient.

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

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

Despite having 5 parameters and no schema-level descriptions, the description covers every parameter's meaning, defaults, and constraints, and explains the delivery side-effect well. It doesn't explicitly describe return values, but an output schema exists. It also doesn't explicitly state the behavior after ack_message for non-urgent messages, but that's a minor edge case. Overall, highly complete for an agent to use correctly.

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

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

Schema description coverage is 0%, so the description bears full responsibility for parameter semantics — and it fulfills it. It explains `body`, `urgency`, `scope_type` (with its sub-values global/project/task/source and what to pass in `scope_value`), and `ttl_hours` defaults and bounds. It essentially compensates for the empty schema descriptions, which earns a 5.

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

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

The description begins with a specific verb-resource pair ('Post a message to the user's OWN running agents') and clearly distinguishes this tool from siblings like ack_message and save_turn. The subsequent details about delivery via Vilix read calls and its push-channel behavior further pin down exactly what this tool accomplishes, leaving no ambiguity about its role.

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 explains the mechanism (delivered in the `inbox` field of matching read calls) and gives concrete defaults, maxes, and scope options, giving an agent enough context to decide when to use it. It does not explicitly name sibling alternatives or state when NOT to use it, so it stops short of a 5, but the delivery mechanics and constraints effectively imply appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavior beyond that: newest-relevant-first ordering, optional source filtering, and the limit default/max, all of which help an agent understand what to expect. Nothing in the description contradicts 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 short and front-loads the main purpose before parameter details. The leading 'Optional.' is slightly redundant and adds little, and the opening is a fragment, but overall it is tightly written with no significant wasted 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 read-only tool with two optional parameters and an output schema, the description covers both parameters and the ordering behavior, which is sufficient for basic invocation. It does not explain what 'relevant' means or when the data is populated, but the low complexity and strong annotations keep this from being a serious gap.

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

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

The input schema has 0% description coverage, but the description fully compensates by explaining both parameters: source restricts to one saved platform label (with examples) and limit has an explicit default and maximum. This is exactly the semantic detail an agent needs beyond the bare schema field names.

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

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

The description identifies the resource ('the user's most recent messages') and the ordering ('newest-relevant first'), which is clear enough for an agent to know what is returned. It lacks an explicit verb like 'get' or 'retrieve' and does not explicitly distinguish it from sibling search/context tools, so it is clear but not fully differentiated.

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

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

The description gives parameter usage details such as source restricting to a platform label and limit defaulting to 10, but it provides no guidance on when to use this tool versus alternatives like search_semantic or get_context. There are no explicit scenarios, exclusions, or when-not-to-use instructions.

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

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

Annotations already mark the tool as destructive and not read-only. The description reinforces this and adds an important behavioral guardrail: explicit user consent is required before calling. It does not detail side effects, but the annotations plus this condition provide adequate transparency.

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

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

Two short sentences with the destructive warning front-loaded. There is no filler, and 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 one-parameter destructive tool with an output schema and rich annotations, the description covers purpose, risk, and invocation conditions well. The only minor gap is guidance on sourcing rule_id, but the surrounding sibling tools like list_user_rules make this a small omission.

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

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

Schema description coverage is 0%, and the description says nothing about rule_id beyond the tool name. The agent must infer that rule_id is the identifier of the user_rule and how to obtain it, which is a notable gap for the only required parameter.

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 the exact operation: 'removes a user_rule'. It clearly distinguishes this from sibling tools like add_user_rule, update_user_rule, and list_user_rules, and the verb is specific and 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 gives an explicit invocation condition: 'Only call when the user explicitly asks to delete or remove a rule.' This clearly implies not to call it for other intents, though it does not name alternative tools such as update_user_rule.

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 rich behavior beyond the sparse annotations: fire-and-forget semantics, server-side deduplication with 'deduped: true' responses, drift detection via assistant_message_sha256 ('drift: true'), and safe re-send behavior. While idempotentHint=false is conservatively set, the description precisely documents the actual dedup guarantees (content-based within a short window, turn_id-based forever), which supplements rather than contradicts the annotation.

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

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

The description is long but every sentence earns its place — the most critical behavioral constraint (non-blocking, reply-first) is front-loaded, and each paragraph covers exactly one parameter or policy. Given 0% schema coverage and 7 parameters, this density is appropriate rather than 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?

An output schema exists, so return-value documentation is not required, and the description covers everything else an agent needs: call ordering, retry and catch-up semantics, parameter semantics for all non-obvious fields, idempotency behavior, and the integrity-checking mechanism. No operational gaps remain for a tool of this 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?

Schema description coverage is 0%, so the description bears the full burden — and it delivers. chat_id ('omit or null to start a new conversation; otherwise reuse the id returned by a prior save_turn'), source (with concrete examples), attachment_context (same summary as get_context), turn_id (retry never double-saves), and assistant_message_sha256 (integrity check, not a gate) are all given meaning the bare schema lacks. It also clarifies that assistant_message is 'the reply as actually sent, not a draft.'

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

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

The opening sentence — 'Persist this exchange' — names a specific verb (persist/save) and resource (the conversation turn), making the tool's function instantly unambiguous. It is clearly differentiated from the sibling list, which is dominated by retrieval tools (search_keyword, recent_messages, get_context), and this is the only persistence/write tool for conversation history.

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 sequencing guidance: 'Send your reply to the user FIRST, then call this after (or alongside) it; do not block or delay the user-visible reply.' It also specifies failure-handling policy (retry once if the environment allows, otherwise catch up on the NEXT turn) and cross-tool consistency with get_context for attachment summaries. 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?

The description adds useful behavioral details beyond the annotations: it clarifies the search scope ('user's past messages'), the source restriction to platform labels, and the limit default/max. These details help an agent predict behavior without contradicting the safe readOnly/idempotent hints.

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 short and front-loads the core purpose before parameter details. The stray 'Optional.' at the beginning is unnecessary and slightly confusing, costing it a perfect score, but the rest is efficient and 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 covers scope and parameter semantics, and the output schema handles return values. However, it lacks guidance on choosing between search_keyword and search_semantic, and does not clarify exact matching behavior (e.g., phrase matching, substring, case sensitivity). Given the tool's simplicity, this is adequate but not complete for an agent to use it optimally.

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

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

With 0% schema description coverage, the description compensates by explaining that `source` restricts to a platform label (with examples) and that `limit` defaults to 10 and maxes at 25. The `query` parameter is implicitly understood as the keyword/full-text search term, though additional details like case-sensitivity or matching semantics would strengthen 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 names a specific verb ('search') and resource ('the user's past messages'), and the qualifier 'Exact keyword / full-text' distinguishes it from the sibling search_semantic. Even without naming the sibling, the contrast is clear and an agent can separate the two intents.

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

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

Usage context is implied by 'Exact keyword / full-text search' — an agent can infer it should be used when exact matches are desired rather than semantic similarity. However, the description does not explicitly say when to use this tool over search_semantic or recent_messages, nor does it mention any exclusions or when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the burden is lower. The description adds useful behavioral context: the search covers past messages and source restricts to saved platform labels.

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?

Compact and front-loaded: the core action appears in the first sentence, and parameter details are backtick-formatted. 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?

Complete for a simple read-only search: required query is obvious, optional parameters are explained, and an output schema exists to define returns. A brief note on when to prefer search_keyword would make it 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 provides no descriptions (0% coverage), but the description explains source's allowed values and limit's default/max. Query's role is evident from the tool name and first sentence.

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

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

Opens with a specific verb and resource: 'Meaning-based search over the user's past messages.' This distinguishes it from sibling search_keyword by modality and from get_context by scope.

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

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

Explicitly says to use when get_context isn't enough, with a concrete example (something specific from before). It doesn't explicitly contrast with search_keyword, but the 'meaning-based' framing implies the choice.

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

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

With all annotations set to false, the description adds an important behavioral trait: omitted fields are preserved rather than overwritten with defaults/null. This prevents a misinterpretation of the schema's nullable default values and honestly reflects the update semantics.

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 front-loaded sentence with no filler: the first clause states the action and target, and the second clause carries the key partial-update caveat. It is as compact as possible while remaining informative.

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 five-parameter update tool with an output schema and no nested objects, this description covers the main invocation caveat and field scope. It leaves status values and project_rules semantics to be inferred from names, but the schema plus output schema cover the remaining mechanical details.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does so by naming the four updatable fields and clarifying that only supplied fields are modified. project_id is not described, but its role as the target identifier is clear from the phrase 'a project's' and the required field in the schema.

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

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

The description opens with a specific verb and resource ('Update a project's') and enumerates the exact mutable fields: title, description, project_rules, and status. This clearly distinguishes it from create/delete/get/list project tools and the resource-scoped sibling update_* tools.

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

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

The second sentence, 'Pass only the fields you want to change,' gives explicit guidance for the tool's partial-update usage pattern. It doesn't name alternative tools or list exclusions, but the resource-specific wording makes when to use it unambiguous given the sibling set.

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?

It discloses partial-update behavior, scope re-assignment semantics, and the fact that enabled=false hides rather than deletes. These go beyond the bare annotations (readOnly=false, destructive=false) and help the agent understand the operation's effects. It does not mention null-vs-omit semantics, but it does not contradict any annotation.

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

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

Three sentences, each carrying distinct value: the partial-update rule, scoping behavior, and the hide-not-delete behavior. It is front-loaded and contains 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?

The description covers the trickiest aspects (scope and enabled behavior) and an output schema exists, so return values need no explanation. The main gap is the null-vs-omit semantics for clearing fields like body or description, which is especially relevant because most parameters are nullable and default to null. This could lead an agent to accidentally null a field by passing null when it meant to leave it unchanged.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain project_id and enabled meaningfully, and the 'pass only fields you want to change' rule clarifies the general PATCH-style usage. However, name, body, and description are left to inference, and the schema's nullable values make the distinction between omitting a field and passing null ambiguous.

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 'Update a skill' — a specific verb and resource — and immediately clarifies that it is a partial update ('pass only the fields you want to change'). It also distinguishes itself from delete_skill by noting that disabling a skill hides it 'without deleting it.'

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

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

The description gives clear conditional usage: pass project_id to attach, pass 'global' to make global, omit project_id to leave scope unchanged, and set enabled=false instead of deleting. It does not explicitly say 'use create_skill for new skills,' but the context of updating an existing skill makes that 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 provide only readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description carries the burden of explaining mutation behavior. The phrase 'Pass only the fields you want to change' clearly discloses partial-update semantics, which is valuable beyond the schema and annotations. It does not describe side effects or return behavior, but the output schema covers return shape.

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 no filler. It front-loads the tool's purpose and immediately follows with the critical partial-update instruction, making it easy to parse quickly.

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

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

For a six-parameter mutation tool with an output schema and no parameter descriptions, the definition is adequate but not complete. It covers the core update behavior and partial-update semantics, but it omits guidance on when to prefer update_task_state and provides no detail about accepted values for the enumerated-looking string fields. The presence of an output schema reduces the need to describe return values.

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

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

Schema description coverage is 0%, so the description must compensate. It lists the five updatable fields and clarifies that omitting a field means it should not change, which adds real meaning beyond the nullable schema properties. However, it does not explain the allowed values or semantics of 'state', 'priority', or 'plan_status', leaving some burden on the agent to infer valid inputs.

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

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

The description uses a specific verb ('update') and resource ('task'), and explicitly enumerates the updatable fields: title, body, priority, state, plan_status. Saying 'Full task update' distinguishes this from the more focused sibling update_task_state without needing to open 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 implies this tool is the broad update option versus the narrower update_task_state sibling, but it never explicitly states when to use one over the other. There is no when-not-to-use guidance or mention of alternative tools such as create_task or update_task_state.

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

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

Annotations already establish that this is a mutating, non-idempotent, non-destructive operation. The description adds concrete behavioral detail: it changes the task state and may overwrite or set plan_status, and it is intended specifically for post-execution updates. This is useful value beyond the structured hints.

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

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

Two sentences with no filler. The first sentence states the operation and parameter semantics; the second sentence gives usage context. Everything 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 three-parameter state-transition tool, the description covers the input semantics, the valid state values, and the specific execution context. An output schema exists, so return-value details do not need to be restated. No critical information 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?

With 0% schema description coverage, the description carries the parameter-documentation burden. It compensates well for state by listing all valid values and for plan_status by labeling it as a one-line field, while task_id is self-evident from its title. Some detail about plan_status's null behavior is left to the schema default.

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 identifies a specific action — 'Flip a task's state' — and enumerates the exact allowed values (todo|doing|blocked|done), plus the optional plan_status field. This clearly distinguishes it as a focused state-transition tool rather than a general task-update tool.

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

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

The phrase 'narrow AI-after-execution path — use this after you do work on a task' provides a clear trigger condition for when to use the tool. It does not explicitly name or contrast the sibling update_task tool as the alternative for broader edits, so it falls just short of full exclusion 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 indicate this is not read-only and not destructive; the description adds only a small amount of context by specifying that the target is an existing user_rule. It does not disclose overwrite semantics, permissions, or failure behavior, but the annotation coverage lowers the burden somewhat.

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 the verb and resource front-loaded and no redundant words. It is efficient, though slightly sparse in supporting details.

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

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

For a simple two-parameter update with an output schema and annotations, the description is minimally adequate: it states what is updated and that the target is an existing rule. It omits guidance on how to locate rule_id and what happens if the rule does not exist, which are meaningful gaps for an agent.

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

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

Schema description coverage is 0%, so the description must clarify parameter meaning. It explains that 'text' is the field being updated, but it only loosely implies that 'rule_id' identifies which rule to update. No format, source, or constraints are given for rule_id.

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

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

The description uses a specific verb ('Update') and resource ('text of an existing user_rule'), clearly distinguishing it from sibling tools like add_user_rule and remove_user_rule. The 'existing' qualifier reinforces that this is an update operation, not a create or delete.

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 explicit guidance on when to use this tool versus alternatives like add_user_rule or remove_user_rule. It also does not mention prerequisites, such as how to obtain the rule_id or whether the rule must already exist beyond the word 'existing'.

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