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

No annotations provided, so description carries full burden. It details audit logging, destructive side effects (token invalidation, Stripe refunds, session revocation), and error codes. No 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?

Well-structured with sections, but slightly verbose. Front-loaded purpose and actions list. Earns its length but could be trimmed.

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, and description only specifies return for team_billing. Other actions lack output description. Covers actions but misses return values for most, leaving a gap for the 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 coverage is 100% but description adds behavioral context for each action beyond schema descriptions (e.g., token invalidation for team_suspend). However, some parameters like description and payment_intent_id are not elaborated.

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 it's for super-admin operations with specific verbs like suspend, adjust, force-rotate, and browse. It distinguishes from sibling tools by noting that routine tenant operations use team-scoped 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?

Explicitly provides when to use (incident response, billing adjustments, security review) and when not (routine tenant ops). Also mentions restriction to super-admin role with HTTP 403 for others.

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, but the description adds significant context: 'rollback (DESTRUCTIVE) — ... current state is lost unless already snapshotted.' It also marks other actions as read/write. This goes well beyond 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 well-structured with bullet points for each action, front-loaded with an overall summary. Every sentence is informative and necessary, with no extraneous text.

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

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

Despite having no output schema, the description hints at return values for each action (e.g., 'Past config snapshots with timestamps,' 'Last execution status, queue depth, error counters'). It covers all actions adequately for an agent to select and use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining action-dependent parameters: 'Every action requires agent_id; remaining params depend on action.' It also elaborates on parameters like mode for skill_sync/tool_sync, which is not obvious from the schema alone.

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

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

The description starts with a clear summary: 'Auxiliary agent operations beyond core CRUD.' It explicitly lists all actions and distinguishes from the sibling 'agent_manage' tool by stating 'For create/update/delete/toggle use agent_manage.' This provides unambiguous differentiation.

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

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

The description explicitly tells when to use this tool vs. alternatives: 'For create/update/delete/toggle use agent_manage.' It also categorizes each action with (read), (DESTRUCTIVE), or (write), guiding appropriate usage. No additional exclusions 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?

Annotations only provide `destructiveHint=true`. The description goes well beyond by detailing that delete is destructive and performs a soft-delete recoverable for 30 days, mentions validation of provider/model at creation/update, and notes that partial updates are allowed. No contradictions 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 and sibling differentiation. It then uses a concise bullet list to detail each action, with no extraneous information. 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?

Despite having 28 parameters, no output schema, and complex nested objects, the description covers all key behaviors: CRUD actions, validation, soft-delete, and defaults. It gives sufficient context for an AI agent to select and invoke the tool correctly.

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

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

The input schema has 100% description coverage, but the description adds value by grouping parameters into actions, explaining defaults (limit default 10, max 100), and clarifying that `confirm=true` is required for deletion. It also states validation of provider/model at create/update time, which is not in the schema. This goes beyond baseline.

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

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

The description clearly states 'Core CRUD for AI agents in the caller's team' and enumerates all seven actions (list, get, create, update, delete, toggle_status, templates). It also distinguishes itself from the sibling tool `agent_advanced` by specifying what that sibling is for, making purpose 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 tells when to use this tool versus `agent_advanced` ('For runtime inspection, rollback, skill/tool wiring or feedback use `agent_advanced`'). It also gives a brief overview of each action, guiding the agent on when to invoke which action.

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 detail beyond destructiveHint annotation: audit-logging, domain events, and action consequences (approve unblocks, reject terminates). 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?

Efficient structure: opening sentence defines purpose, then bullet points for each action with parameter details. 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?

Despite 10 parameters, no output schema, and multiple actions, the description covers all necessary context: when to use, per-action parameters, outcomes, and side effects. Agent can correctly select and invoke the tool.

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

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

Schema coverage is 100% so baseline 3, but description adds meaning by associating parameters with specific actions and clarifying usage (e.g., comment optional for approve, reason required for reject, form_data must match schema). Overcomes schema's over-required fields.

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

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

Clearly defines tool as managing approvals and human-task completion. Explicitly lists actions (list, approve, reject, complete_human_task, webhook_config) and their effects, distinguishing from sibling manage 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?

States when to use: unblock workflow steps or submit form data for human_task DAG nodes. Describes effects of each action but does not explicitly mention alternatives or when not to use.

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, but the description asserts 'Read-only access.' This is a direct contradiction: read-only tools should not have destructiveHint. The description fails to disclose why it is marked destructive, misleading the agent about potential side effects.

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

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

Description is front-loaded with purpose, followed by a bulleted list of actions with precise details. Every sentence is informative; no fluff or 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?

Despite strong parameter documentation, the glaring contradiction between 'read-only' description and destructiveHint annotation undermines completeness. The agent lacks understanding of whether this tool can cause harm. Otherwise, the description would be 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 has 100% coverage, but the description adds significant value: explains default version behavior, signed URL expiry (~5 min), content encoding for binary types, and clarifies each action's output. This goes well beyond the schema definitions.

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 'Read-only access to artifacts' and enumerates four specific read actions (list, get, content, download). It effectively communicates the tool's purpose and distinguishes it from other management tools that likely support write operations.

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 scenarios: retrieving artifacts and their versions. It provides context for when to use this tool (read-only operations) but does not explicitly state when not to use it or mention alternatives among 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?

Beyond the destructiveHint annotation, the description details authorization levels per action, notes that send_message triggers a synchronous tool-loop LLM call consuming team credits, and explains that conversation_clear erases all messages. This adds valuable behavioral context not captured in 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 concise and well-structured with bullet points for each action. It front-loads the purpose and efficiently covers authorization, parameters, and side effects without unnecessary verbosity.

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

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

The description is thorough for a tool with multiple actions, covering purpose, authorization, parameter behaviors, and destructive effects. However, it lacks details on return values for actions like list/get, which would improve completeness 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?

Input schema has 100% description coverage, but the description adds usage context (e.g., omit conversation_id to start new, optional limit and context_type filter for conversation_list). This provides meaningful guidance beyond the schema itself.

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 that the tool manages FleetQ AI assistant conversations, listing specific actions (conversation_list, conversation_get, send_message, conversation_clear). It distinguishes itself from sibling tools by focusing on the in-app chat panel that can call MCP tools, making its purpose 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 provides clear context for when to use each action based on authorization roles (read for all, write for Member+, destructive for Admin/Owner). However, it does not explicitly exclude alternatives among sibling tools or specify when not to use this tool, missing a small opportunity for clearer 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 discloses that side effects depend on script capabilities, notes the 'dependency_unavailable' error, and categorizes actions as 'write' (run) or 'read' (others). This aligns with the destructiveHint: true annotation and adds context beyond it, though detailed effects per script are left to the script's capabilities.

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 lengthy but well-structured with bullet points for each action and clear parameter groupings. It is not overly verbose given the complexity of the tool, and every sentence adds useful information.

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

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

For a tool with 15 parameters, multiple actions, no output schema, and complex dependencies, the description covers actions, error conditions, prerequisite setup, and parameter usage. It references external documentation for further details. Minor gaps: no description of return values for each action.

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% coverage, but the description adds meaning by grouping parameters per action (e.g., inline vs skill mode), explaining the relationship between 'policy' and 'policy_structured', and specifying which parameters are relevant for each action. This goes beyond the schema's property 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 clearly states the tool executes, validates, and audits Boruna scripts, and lists specific actions (run, validate, etc.) with their purposes. It distinguishes from sibling tools (e.g., admin_manage, agent_manage) by focusing on Boruna-specific functionality.

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 for when to use each sub-action (e.g., 'run for execution, validate for syntax check') and mentions a prerequisite (mcp_stdio Tool record). However, it does not explicitly compare this tool to 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?

Beyond the destructiveHint annotation, the description labels actions as read/write/destructive and explains that disconnect terminates the bridge session requiring re-registration. This adds useful behavioral context about side effects.

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

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

The description is well-structured with a brief overview followed by bullet-pointed actions. It is concise but informative, with few wasted words. Could be slightly more terse.

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 main actions but lacks details on return values for read actions, error handling, and does not clarify that endpoint_id is required in schema but only relevant for specific actions. This leaves gaps for an agent to fully utilize the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add new semantics for parameters beyond listing actions; it mentions endpoint_id in context of toggle but schema already covers it. No extra value added.

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 as a WebSocket relay for cloud experiments to reach private endpoints, and lists specific actions (status, endpoint_list, endpoint_toggle, disconnect) with precise verbs and resources. It distinguishes itself from siblings by its unique domain of bridge/private endpoint management.

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 managing the bridge but does not explicitly state when to use this tool vs alternatives, nor does it provide when-not-to-use guidance. Given the many sibling tools, explicit differentiation would enhance this dimension.

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 claims the tool is read-only ('does not move money'), but the annotation destructiveHint: true indicates the tool may be destructive. This contradicts the description, severely undermining 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?

The description is well-organized with a clear overview and bullet list of actions. It is slightly verbose but earns each sentence. Front-loads the key 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?

No output schema is provided, so the description must explain return values. It partially does (check returns pass/fail, forecast projects spend), but lacks detail on output structure for summary. Adequate but not complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context (e.g., check returns pass/fail), but most parameter meaning is already in schema descriptions. No significant added value beyond 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 it provides budget overview, pre-flight cost guards, and spend forecasting. It lists specific actions (summary, check, forecast) and explicitly says it is read-only, distinguishing it from other 'manage' sibling tools that likely perform mutations.

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 advises using the 'check' action before expensive jobs to avoid budget exhaustion events, providing clear usage context. However, it does not mention when not to use the tool or alternatives among siblings, slightly reducing clarity.

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 far beyond the destructiveHint annotation by explicitly labeling actions as read, write, or destructive, detailing cascading effects (e.g., delete revokes all widget tokens), and noting credit consumption. This provides rich behavioral context that annotations alone do not cover.

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

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

The description is well-structured with a concise overview, a bulleted action list, and clear categorization. It is slightly long due to the number of actions, but each sentence serves a purpose. Minor redundancy could be trimmed without losing clarity.

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

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

For a complex tool with 23 parameters and 11 actions, the description covers the core aspects: action types, destructive behavior, credit usage, and optional filters. It does not describe output format or pagination details, but these are partially covered by the input schema. Overall, it provides sufficient context for safe 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?

With 100% schema description coverage, the parameter semantics are already well-documented in the input schema. The tool description adds no additional parameter-specific details beyond listing actions, so it meets the baseline but does not surpass 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 clearly states the tool manages 'Embeddable chatbots backed by an existing FleetQ agent' and lists all actions. While it differentiates from other tool management siblings by focusing on chatbots, it does not explicitly contrast with sibling tools like agent_manage or assistant_manage.

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 other similar manage tools. The description lacks any 'when to use' or 'when not to use' context, leaving the agent to infer 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?

Beyond the destructiveHint annotation, the description details encryption at rest, that secret_data is never returned by get, hard delete irrecoverability, and OAuth workflow. This adds substantial behavioral context.

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

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

The description is relatively long with multiple paragraphs. While it front-loads the main purpose and uses bullet points for actions, some redundancy exists (e.g., repeating action types also in schema). Could be more concise.

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 actions and key behaviors but lacks return value descriptions for most actions (e.g., list, create). Since no output schema exists, this omission reduces 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 coverage is 100% with detailed parameter descriptions. The description lists actions with associated parameters but does not add new meaning beyond the schema, so baseline score 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 clearly states the tool as an 'Encrypted credential vault for external services' and lists all actions. This distinguishes it from sibling management tools which handle different resources.

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

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

The description provides clear context for credential management but does not explicitly exclude alternative tools or provide when-not-to-use guidance. Since no other credential tools exist, the context is 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?

Beyond the destructiveHint annotation, the description discloses behavioral traits: execute is async, returns execution_id, polls via execution_status, includes soft-delete, and reserves budget. This adds significant behavioral context beyond minimal 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 well-structured with a clear top-level explanation and bulleted actions. It is concise given the tool's complexity, though some redundancy 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?

Given the 15 parameters, no output schema, and multiple actions, the description provides a fairly complete picture. It covers all actions, async nature, and constraints. Missing details on return values and some parameters, but overall adequate.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context about async behavior and soft-delete for some actions. However, it mentions an 'agents[]' array in the create action that does not correspond to a schema parameter (instead using coordinator_agent_id and qa_agent_id), which may confuse.

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 manages multi-agent crews with actions like CRUD and execution. It distinguishes the tool by focusing on crew coordination, but does not explicitly differentiate from sibling tools like team_manage or agent_manage.

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 guidance on async execution and polling, and mentions that agents must be real IDs. However, it lacks explicit when-to-use or when-not-to-use compared to alternatives. It implies usage but does not give clear exclusions.

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

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

The description goes beyond the destructiveHint annotation by explicitly labeling theme_delete and template_delete as destructive and explaining the blockage when a theme is in use. It also discloses that template_generate consumes credits and compiles MJML server-side. This level of detail exceeds the annotation's bare 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 moderately long but well-structured into paragraphs for general info, theme actions, and template actions. Each sentence carries relevant information (e.g., credit consumption, MJML compilation). Minor redundancy could be trimmed, but overall it's 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?

Given 34 parameters and no output schema, the description covers key workflows: dependencies (theme deletion blocked), credit costs for generation, and the difference between MJML and HTML storage. It lacks details on error responses or pagination for list actions, but it adequately addresses 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?

With 100% schema coverage, the baseline is 3. The description adds value by grouping parameters into actions (e.g., theme_create uses name and styles object) and explaining parameter relationships (e.g., mjml_body preferred over html_body, theme_id injects brand colors into generated MJML). It also notes default values for several fields.

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

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

The description clearly states it manages email themes (visual styling) and templates (transactional + marketing copy). It lists specific actions for themes and templates, including AI generation via template_generate. This distinguishes it from sibling tools, which have different domains (e.g., admin_manage, credential_manage).

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 context for when to use each action, such as distinguishing theme operations from template operations and noting that template_generate consumes credits. It also explains a dependency: deleting a theme fails if templates reference it. While it doesn't explicitly compare to alternatives (e.g., outbound_manage for sending), the guidance is clear for the tool's scope.

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 explicitly warns that apply is destructive and irreversible without manual rollback, going beyond the destructiveHint annotation. It also describes read vs. write actions.

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, well-structured with bullet points for actions, and front-loads the purpose. Every sentence adds value.

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 workflow, actions, and rollback details. No output schema exists, but it mentions what analyze returns. Sufficient 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 input schema has 100% coverage with descriptions for all parameters. The description adds context for the action parameter's values, but the schema already handles semantics well.

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 it manages AI-generated improvement proposals and lists specific actions (list, analyze, approve, apply, reject). It differentiates from siblings by its focus on evolution proposals.

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 when to use each action (e.g., analyze returns rationale, apply is destructive) and mentions rollback via another tool. It lacks explicit comparisons to alternatives but provides sufficient context.

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

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

The description adds significant behavioral context beyond the annotations: it details the state machine, lifecycle transitions, and notes that `kill` is destructive and terminal. It also mentions budget reservation on `start` and graph-aware BFS reset for `retry_from_step`. While annotations already indicate `destructiveHint: true`, the description enriches the behavioral model.

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

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

The description is well-structured with a clear opening statement about experiments and a bullet list of actions. It is informative without being overly verbose, though the state machine detail could be considered slightly heavy for a function description. Overall, it is 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 tool's complexity (15 parameters, 4 required, no output schema), the description fails to explain return values or error states for actions. While it covers actions and states, it does not describe expected outputs (e.g., what `list` returns, cost breakdown format). This is a notable gap for a tool with no 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?

With 100% schema description coverage, the schema already documents all parameters. The description provides a high-level mapping of actions to required parameters (e.g., `list` uses optional `status`, `workflow_id`, `limit`), but does not add deeper semantic meaning beyond what the schema offers. 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 explicitly states that the tool manages experiments, which are the core unit of work. It lists all actions (list, get, create, start, etc.) and explains the 20-state machine, making the tool's purpose very clear and distinct from sibling tools focused on other domains.

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 by listing actions and their effects, but it does not explicitly state when to use this tool versus alternatives (e.g., other manage tools). There is guidance on using `valid_transitions` to check allowed state transitions, but no comparative guidance or 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?

Beyond the destructiveHint annotation, the description explicitly marks repo_delete as DESTRUCTIVE, notes that file_write and commit push to remote, details concurrency safety via AtomicCommittingGitClient, and explains encrypted credential storage. This adds rich behavioral context.

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

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

The description is well-organized with bullet points grouping repo actions and file/branch/commit actions, and front-loads the main purpose. However, it is slightly verbose and could be more concise without losing clarity.

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 complexity (25 parameters, many actions), the description covers main categories and behaviors (destructiveness, concurrency, push). However, it lacks return value information (no output schema), error handling notes, and does not clarify conditional parameter requirements (e.g., required fields depend on action). The required array in the schema is misleading without further explanation.

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

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

Schema coverage is 100%, with each parameter having a description in the schema. The tool description adds some context (e.g., repo_create uses credentials object, file_write pushes) but does not significantly elaborate on individual parameters beyond what the schema already provides. 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?

The description clearly states the tool connects, browses, and modifies external git repositories, listing specific actions (e.g., repo_list, file_read, commit) and supported providers (GitHub, GitLab, etc.). This specificity distinguishes it from sibling tools like integration_execute or workflow_manage.

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 enumerates all possible actions but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention when not to use it. Usage is implied through action descriptions, but no comparative or contextual advice is given.

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

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

Annotations already signal destructiveHint:true. The description adds that it executes actions (implying mutation) and gives examples, but does not disclose additional behavioral traits such as required authentication, potential side effects, or rate limits. With annotations covering destructive nature, the description's extra behavioral context is minimal.

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 examples. Every part earns its place; 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 tool with 3 parameters and no output schema, the description is fairly complete. It explains the action concept and gives examples, but does not cover return values or error behavior, which would be beneficial.

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 well-described parameters. The description's examples add context for the 'params' object but do not significantly extend beyond the schema. Baseline 3 is appropriate as the description provides no substantial additional 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 states 'Execute an action on a connected integration' with concrete examples (create_issue on GitHub, send_message on Slack), making the purpose unambiguous and distinguishing it from sibling tools like integration_manage.

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 examples of when to use, but does not explicitly mention when not to use or list alternatives. Given the sibling tools are mostly manage tools, the usage context is clear without exclusions.

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

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

The description discloses behavioral traits like destructiveness for disconnect and side effects for execute, and the annotation already sets destructiveHint: true. However, it does not cover idempotency, rate limits, or auth requirements beyond mentioning OAuth for connect.

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

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

The description is well-structured with a header and bullet points, and most sentences are necessary. However, it is somewhat verbose; could be more concise without losing clarity.

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 complexity (10 parameters, no output schema), the description fails to explain return values for most actions (only mentions 'output normalized to JSON' for execute). Error handling and detailed behavior for list, connect, etc., are missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds examples for credentials and config, but does not significantly enrich parameter understanding 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 manages third-party integrations with six specific actions (list, connect, disconnect, ping, execute, capabilities) and describes each action's purpose. However, it does not differentiate from the sibling tool 'integration_execute', which could cause confusion about when to use each.

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

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

The description provides some usage hints (e.g., 'optional: driver, status filter' for list, and 'DESTRUCTIVE' for disconnect), but lacks explicit guidance on when to use this tool versus alternatives (e.g., sibling integration_execute). No prerequisites or when-not-to-use scenarios are mentioned.

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 critical behaviors: ingestion runs an embedding job consuming credits, search is hybrid cosine similarity with keyword fallback, and delete is destructive. This adds substantial context beyond the annotations, which only indicate destructiveHint.

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 a concise summary, then breaks down each action in a structured bullet list. Every sentence adds value without redundancy, making it easy for an agent to parse.

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

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

Given the tool's complexity and lack of output schema, the description covers key aspects: actions, credit cost, search method, and destructive delete. Minor gaps include no explicit mention of return formats for list/search, but overall it is adequate.

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?

While the input schema has 100% coverage with parameter descriptions, the tool description groups parameters by action (e.g., ingest uses knowledge_base_id plus content/url/file_id), adding semantic meaning beyond individual parameter definitions.

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 manages per-team knowledge bases with vector indexing. It lists five specific actions (list, create, ingest, search, delete), each with a clear verb and resource, distinguishing it from sibling 'manage' 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 context for when to use each action, such as listing vs. creating, and notes that ingest consumes credits. It does not explicitly exclude alternative tools, but siblings are distinct categories, so usage context is clear.

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

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

With empty annotations, the description fully discloses behavioral traits: public vs team-scoped actions, install side-effects (copy artifact, increment count), review constraints (one per user per listing), and analytics limited to publisher. No contradictions 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 moderately long but well-structured with bullet points for each action. Every sentence contributes useful information. Minor redundancy in action listings but overall 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?

No output schema exists, but the description does not specify return values for actions like browse or publish. For a tool with 14 parameters and 6 actions, more details on expected outputs 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 coverage is high (93%), and the description adds value by grouping parameters under actions and explaining constraints (e.g., bundle_items format, visibility defaults). However, it does not describe every parameter in 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 clearly states the tool is a 'Cross-team marketplace for shared skills, agents, and workflows' and lists specific actions (browse, publish, install, etc.) with brief explanations. It distinguishes itself from sibling tools (e.g., admin_manage, agent_manage) by explicitly describing marketplace functionality.

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 for when to use different actions: 'browse and categories are public', others operate within the caller's team. It also notes that installing copies artifacts and increments count. However, it does not explicitly state when to avoid the tool or suggest alternatives for similar tasks.

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

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

With no annotations, the description details read/write actions, destructive delete, embedding costs, async upload, errors list (401,403,404,413,422,429,503), and cloud provision note. However, lacks explicit mention of authorization requirements and pagination behavior for list_recent.

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

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

Well-structured: purpose first, then usage guidance, then action list. Each section serves a purpose, though the action list could be slightly more compact. No wasted sentences.

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

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

Covers actions, errors, and cloud note. Lacks explicit return structure for most actions (only search and stats are described). No output schema, so description should explain all return values; missing for list_recent, add, delete, upload_knowledge.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for actions (e.g., search default limit 20, max 100) but does not significantly enhance parameter meanings beyond what the schema provides. No unique insights per 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 clearly defines the tool as 'Team-scoped semantic memory' for short notes, and explicitly distinguishes it from sibling knowledge_manage by noting scope and content type (unstructured short notes vs document corpora).

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

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

States when to use: to recall stable facts across runs or remember decisions. Explicitly provides a negative case: 'Do NOT use for transient run-state — use the experiment artifact system instead.' Clearly identifies alternatives.

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

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

With no annotations, the description fully discloses behavioral traits: save uses upsert semantics, delete cancels pending outbound actions, test counts against rate limits and budgets. It mentions middleware (ChannelRateLimit, TargetRateLimit) and recording as OutboundAction, giving the agent a complete 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 well-structured with a clear introductory sentence followed by bulleted actions. It is slightly verbose but every sentence adds information. No fluff, but could be trimmed slightly for brevity.

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

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

Given the tool's complexity (6 parameters, multiple actions, no output schema), the description covers all necessary aspects: action semantics, rate limits, upsert behavior, and destructive effects. An agent can confidently select and invoke the tool based on this description.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond schema by explaining save replaces existing connectors, delete is destructive, and test sends real payload. However, details on credentials and is_active remain schema-level only, so not a full 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 clearly identifies the tool as managing outbound delivery connectors for messaging channels. It lists specific actions (list, get, save, delete, test) with brief explanations, and distinguishes the tool from siblings by focusing on connector lifecycle and channel types.

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 usage context for each action (e.g., 'save (write — upsert)', 'delete (DESTRUCTIVE)', 'test (write — sends a real test payload)'). It implicitly guides when to use which action but does not explicitly contrast with sibling tools like credential_manage or integration_manage.

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 empty, so description bears full burden. Discloses side effects for each action: email update re-issues verification and clears email_verified_at, password_update is destructive and revokes sessions, social_unlink may be rejected if no remaining auth method. Also mentions rate limits and audit logging.

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

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

Well-structured: overview, usage guidance, then action list with behaviors. Every sentence adds value. 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?

Given complexity (multiple actions, side effects, no output schema), description covers all actions, their parameters, side effects, and error cases (401, 403, 422, 429). Missing explicit return format but described inline (e.g., profile object fields, 2fa_status returns {enabled, recovery_codes_remaining}). Highly 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 38% (low), but description adds semantics for action-specific parameters (e.g., update fields are optional, password_update requires current_password/password/password_confirmation, provider enum values). Does not describe deadline_ms but it is optional. Compensates well for low 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?

Clearly states it operates on the caller's own profile/account settings, lists supported actions (get, update, password_update, etc.), and distinguishes from sibling tool admin_manage. Specific verbs and resource identified.

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 when-to-use instructions ('agent or assistant needs to read/update the current user's profile...'), excludes account creation (self-service signup), and references admin_manage as an alternative for managing other users.

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 destructiveHint annotation, the description reveals that trigger_run costs credits, schedule_nlp calls an LLM, and archive is reversible. This adds useful behavioral context without contradicting 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 well-structured with a clear first sentence and bullet-pointed actions. It is appropriately sized for the complexity, though slightly verbose in places.

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

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

Given the tool's complexity and lack of output schema, the description covers lifecycle states, actions, and side effects fairly completely. It could briefly mention return types for read actions, but overall it provides sufficient 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?

With 100% schema coverage, the schema already describes parameters fully. The description adds minor value by grouping actions and mentioning 'project_id + any creatable field' for update, but does not significantly enhance parameter understanding.

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 tool as managing project containers for scheduling workflows, with a comprehensive list of actions. It distinguishes itself from siblings by focusing on project lifecycle and scheduling.

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 for each action (e.g., 'write' vs 'read') and includes important notes like cost for trigger_run and LLM usage for schedule_nlp. However, it does not explicitly compare to sibling tools or state when not to use this 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?

No annotations exist, so the description carries the full burden. It discloses side effects ('writes update KG and trigger downstream rule evaluation'), error codes (401, 403, 404, 422, 429, 503), idempotency for connector actions, polling intervals (5 min), and cloud-specific restrictions. While not exhaustive (e.g., no mention of retry behavior), it is quite thorough.

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

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

The description is well-structured with clear sections (purpose, when to use, action list, cloud note, side effects, errors). It is front-loaded with essential information. While it is lengthy (due to many actions), it is organized and every sentence adds value, making it efficient 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?

Given the complexity (28 parameters, no output schema, nested objects), the description covers all major aspects: actions with config details, knowledge graph operations, side effects, error codes, and cloud-specific note. It does not describe return values, but since no output schema exists, this is acceptable. The description provides sufficient context for an agent to understand the tool's capabilities and boundaries.

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%, but the description adds significant value by grouping actions and explaining the behavior of each connector action (e.g., 'Polls every 5 min' for ticket, 'Pushes signals on incident events' for alert). It provides context for config objects and sub-actions (e.g., subscription: 'list, create, delete'). This goes beyond the schema's field-level descriptions.

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

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

The description clearly states the tool handles inbound signal sources and knowledge graph read/write, with a specific verb ('bind' and 'query/extend'). It distinguishes from sibling `signal_manage` by explaining that this tool wires up connector configurations while the sibling operates on already-ingested signals, providing clear differentiation.

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

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

Explicit guidelines: 'When to use: bind a new external system to FleetQ so its events become signals...or query/extend the team's knowledge graph.' Also explicitly states when NOT to use: 'Do NOT use to send outbound messages — use `outbound_manage` for that.' This provides clear context and alternatives.

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

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

Annotations provide destructiveHint: true, and the description amplifies this by labeling connector_binding_delete as 'DESTRUCTIVE' and explaining consequences ('future signals from that connector go unrouted'). It also notes that ingest 'runs trigger evaluation' and email_reply 'sends email via the team's outbound email connector', adding behavioral context beyond 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 well-structured with bullet points for actions, making it easy to scan. It covers all major aspects without excessive verbosity. The introductory line about signals could be slightly trimmed, but overall it's efficient for the complexity.

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

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

Given 24 parameters, no output schema, and multiple actions, the description covers the core behaviors but lacks return value details for list/get actions and error handling. The deadline_ms parameter is not mentioned in the description. While it provides sufficient context for most uses, some 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 coverage is 100% with detailed parameter descriptions, so the tool description adds little new information about parameters. It lists which action each parameter relates to implicitly, but the schema already provides restrictions (e.g., 'search only'). Baseline of 3 is appropriate as the schema carries the 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 clearly states it manages inbound signals from connectors, lists all supported actions with specific verbs (list, get, ingest, etc.), and explicitly distinguishes from sibling tool `signal_connectors`. This provides a specific verb+resource scope and differentiates from 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 directly states 'Operates on already-ingested signals; for connector setup use `signal_connectors`', giving explicit when-to-use and when-not-to guidance. Each action is described with its effect (read/write/destructive), making it clear when each action is appropriate.

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

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

With no annotations, the description fully shoulders the burden. It details the effects of each action (read/write/destructive), versioning behavior, soft-delete with 30-day retention, costs and rate limits for direct execution, sandbox restrictions (network-disabled, max 60s, 256 MB), and lists possible error codes. This is comprehensive.

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 lengthy (over 500 words) but well-organized with sections for CRUD, direct execution, cloud notes, and errors. Given the tool's complexity (multiple actions, 16 parameters, no output schema), the detail is necessary. A minor reduction could improve conciseness, but it remains clear and scannable.

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

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

The description fully covers the tool's purpose, all actions, parameter usage, error handling, cost implications, and cloud-specific limitations. Despite lacking an output schema, the description provides enough context for an agent to select and invoke the tool correctly across all scenarios.

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?

Although schema description coverage is 100%, the description adds significant context beyond parameter names and types. It groups parameters under actions (e.g., 'create (write) — name, type, config (type-specific JSON). Returns skill_id.'), explains the meaning of type, framework, and data_classification, and clarifies defaults and constraints for limit, deadline_ms, etc.

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 defines the tool as managing AI skills (reusable units) and lists all CRUD and direct execution actions. It explicitly distinguishes from siblings, such as warning not to use for raw LLM calls (use assistant_manage) and noting that supabase_edge_function is not exposed in cloud (use integration_execute).

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 includes a 'When to use' section that specifies appropriate use cases (building reusable primitives, one-off skill execution) and explicitly says what not to do ('Do NOT use for raw LLM calls'). It provides clear alternatives (assistant_manage, integration_execute) and context-specific 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?

With no annotations provided, the description fully carries the burden. It details permission tiers (any authenticated user for reads, is_super_admin=true for writes), audits logging on writes, and specific behavioral consequences like cache_purge causing cross-team cache loss with performance/cost impacts, and runpod incurring immediate billing.

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

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

The description is well-structured with headers for read/write actions, bullet points, and clear sections. It is longer due to high complexity but every section earns its place. Slight redundancy could be trimmed, but overall efficient for the scope.

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

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

Given the tool's complexity (25 parameters, no output schema, nested objects), the description is remarkably complete: it covers all actions, permissions, error codes, and behavioral traits. The only minor omission is not explicitly stating output formats, but that is implied for a system tool.

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

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

Schema description coverage is 100%, baseline 3. The description adds value by grouping actions into read/write and explaining the meaning of sub-actions beyond enum labels (e.g., 'blacklist' sub-actions list/add/remove). However, many parameter details are already covered in the schema, so the marginal gain is moderate.

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 tool as 'Platform system administration, monitoring, and infrastructure control' and lists specific actions (KPIs, health checks, audit log, etc.). It explicitly distinguishes from sibling tools by stating 'Do NOT use for tenant-level operations — those have dedicated tools (e.g. team_manage).'

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 when-to-use examples: 'agent monitoring platform health, on-call investigating an incident via audit log, super-admin adjusting platform-wide settings or purging the semantic cache after a model swap.' It also gives exclusion guidance: 'Do NOT use for tenant-level operations' and points to a specific alternative 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?

Detailed disclosure of behavioral traits: role-based access (owner/admin for writes, viewer/member for read+notifications), audit logging, destructive nature of KMS rotate/revoke, token rotation advice, and error types. Annotations are absent, so description fully informs the agent.

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

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

Well-structured with headers and bullet points, front-loading purpose and role requirements. Though lengthy due to complexity, every sentence adds value without redundancy. Appropriate size for the tool's scope.

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 almost all necessary context: roles, errors (401,403,404,409,422,429), action details, and return values for key actions like 'get'. Despite no output schema, the description provides sufficient information for correct usage.

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?

Adds significant context beyond the input schema: explains action enum with sub-actions, special notes like 'never echoed back' for BYOK, 'plan-enforced' for custom endpoints, and token creation returning once. Schema coverage is 100%, but description enriches each 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 explicitly states the tool manages the caller's team with specific verbs (settings, membership, BYOK, tokens, notifications, KMS keys). It distinguishes from sibling 'admin_manage' for cross-team operations, ensuring clear purpose.

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 when-to-use guidance (agent/assistant managing current team) and when-not (use admin_manage for cross-team). Also clarifies role requirements for different actions, aiding correct invocation.

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?

Despite no annotations, the description fully discloses behavioral traits: side effects depend on underlying tool, platform constraints via bash_policy, credential encryption, soft-delete with caching, and error codes. It also notes that credentials are redacted in responses, adding safety context.

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

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

The description is well-structured with sections, bullet points, and clear headings. It is detailed but each sentence earns its place. Minor redundancy could be trimmed, but it remains highly readable and 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?

Given the tool's complexity (15 parameters, nested objects, no output schema), the description is remarkably complete: it covers all actions, side effects, error codes, caching behavior, and cloud-specific limitations. No gaps are evident for a sophisticated 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 100%, but the description adds value by explaining parameter usage in context (e.g., probe_remote is read-only, delete is destructive with caching). It does not merely repeat schema but enhances understanding.

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: managing MCP servers and built-in tools for agents. It lists specific actions (CRUD, activation, probe) and distinguishes from sibling tools like agent_manage or credential_manage by focusing on tool registration and lifecycle.

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 'When to use' section explicitly guides when to use this tool (e.g., connect new MCP server, toggle availability) and includes a warning not to use it for invocation. It also clarifies cloud-specific restrictions (discover_mcp not available), providing clear context for selection.

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