Supero

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

Annotations already declare readOnlyHint=true, so the description adds only the detail that it returns scope and permissions. This is useful context beyond the annotation, but it does not disclose any side effects, potential failures, or response format. For a simple getter with no parameters, this level of disclosure is adequate but not rich.

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 that front-loads the core action and target. It contains no filler or redundant information, achieving maximum efficiency for a zero-parameter tool.

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

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

For a read-only, no-argument tool, the description covers the essential information: what it retrieves (scope and permissions) and for which entity (current API key). It does not specify return format or error cases, but given the simplicity and the readOnlyHint annotation, the description is sufficiently complete for an agent to call it correctly.

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

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

The tool has zero parameters and the schema coverage is 100% (an empty object). Per the rubric, the baseline for 0 parameters is 4. The description does not need to explain parameters, and it does not, so this dimension is at 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 the verb 'Get' and the resource 'scope and permissions of the current API key', making the tool's purpose unambiguous. It distinguishes itself from siblings like rbac_get_my_access by specifying it targets the API key, not the user's general access. This is a specific and accurate statement of function.

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

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

The description implies usage when you need to inspect the current API key's permissions, but it does not explicitly contrast with alternatives such as rbac_get_my_access or build_whoami. There is no mention of when not to use it or which sibling to prefer, so the agent must infer the appropriate context from the tool's name and purpose 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?

Annotations already declare destructiveHint=true, so the description doesn't need to repeat that. It adds valuable behavioral context: the bind 'VERIFIES the live mapping materialized' and 'nothing goes in the bundle', plus the note that bound live schemas are accessed via ordinary CRUD. These details explain the operational effect beyond the raw destructive flag, making the behavior transparent without contradicting 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—about four sentences—and front-loads the core purpose. It logically organizes mode explanations, prerequisites, and a behavioral note. No filler, and each sentence adds information. It could be slightly more structured (e.g., bullets) but is effective as is.

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

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

For a destructive operation with multiple modes and prerequisites, the description covers the essential: what it does, mode distinctions, discovery requirement, source matching, verification behavior, and that it doesn't bundle. It doesn't mention overwriting behavior or error cases, but annotations cover destructiveness, and the schema covers tenant_binding. Given the complexity, this is fairly 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 0% per the context signal, though the input schema itself includes descriptions for stream_class and tenant_binding. The tool description adds meaning for 'mode' by explaining each enum value's semantics and for 'source' by tying it to discovered streams. However, it does not systematically describe all parameters (connector_id, schema) and relies on the schema's own field descriptions. This partial compensation yields a mid-range score.

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 verb and resource: 'Bind source streams to the app's schemas.' It distinguishes from siblings like build_connect_data_source (which presumably connects a data source) and build_discover_source (which discovers streams) by focusing on the binding action and its modes. The purpose is unambiguous and specific.

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 context: it explains that live modes require discovery to have run, and that source must match a discovered stream. It also differentiates modes (live_read, live_readwrite, sync) and notes the admin-only restriction for live_readwrite. While it doesn't explicitly say 'use this instead of X', the prerequisites and mode selection provide strong guidance for when to invoke 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?

Beyond the annotations (destructive, non-idempotent), the description discloses key behaviors: it reacts to live permission results, auto-refuses certain key patterns, and never echoes secret values. This provides useful transparency about side effects and handling of sensitive data.

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 somewhat verbose and repetitive, repeating warnings about test-only keys and not sending real secrets multiple times. The core message is clear, but it could be tightened without losing 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?

The description covers the tool's purpose, input requirements, restrictions, and behavioral nuances (e.g., refusing live keys, not echoing secrets). It does not explicitly mention success criteria or error scenarios, but given the lack of an output schema, the absence is acceptable. Overall, it provides sufficient context for an agent to 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?

The description enriches the schema for 'config' by providing an example and noting that it is key→value, and for 'service_id' by giving examples like 'stripe_checkout' and 'email'. It also clarifies the restriction on live keys. However, 'project_uuid' remains undescribed in both schema and description, which prevents a perfect score.

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 function: configuring service keys for a project to enable integration at deploy. It provides concrete examples (SendGrid, Stripe) and is specific about the verb ('configure') and resource ('service keys'), making it easy to distinguish from other build tools.

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

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

The description gives explicit usage rules: only test/sandbox keys should be provided, live keys are auto-refused, and production secrets should be handled via the admin panel. It also warns against putting real secrets through the tool. While it does not compare to sibling tools directly, the guidance on when to use and what to avoid is strong.

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 sparse (readOnly=false, etc.), so the description carries the burden. It discloses that the tool returns a connector_id, does not bind schemas, sends credentials to the platform (never echoed), and requires a domain- or project-admin API key. These are behavioral traits beyond the annotations, with 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?

Five sentences, each with a distinct purpose: purpose, return value, workflow, security, auth. Information is front-loaded and there is no filler. 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 15-parameter tool with no output schema, the description covers the return value, workflow, security, and authentication requirements. It does not enumerate parameters (the schema handles that), but it gives an agent enough context to call it correctly. Missing error handling is acceptable given the annotations and schema coverage.

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 67%, so the schema documents many parameters (kind, name, db_type, base_url, etc.). The description adds no parameter-specific meaning beyond a generic reference to credentials, which overlaps with the schema's password description. With moderate coverage, the description does not compensate further, so a baseline 3 is appropriate.

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

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

States a specific verb and resource, enumerates source kinds (database, REST API, warehouse), and explicitly clarifies it does not bind schemas, naming the exact workflow siblings (build_discover_source, build_bind_data_source). This distinguishes it clearly from related tools 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?

Explicitly directs the agent to run build_discover_source then build_bind_data_source, giving a clear sequential workflow and alternatives. Also notes the API key requirement and production security preferences, which are practical usage conditions.

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

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

The description discloses important side effects: it mints a schema_namespace and an API key that is returned only once. This goes beyond the annotations and helps the agent understand the non-idempotent, one-time nature of the result.

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

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

The description is compact and information-dense: purpose, restrictions, side effects, and intended use are all communicated in two sentences without unnecessary detail.

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 sufficient for the intended use: it names required context, side effects, and the one-time API key return. It does not describe the full response shape or error conditions, but the lack of an output schema makes that less critical.

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

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

The schema already covers 80% of parameters with descriptions. The tool description adds context about schema_namespace and API key creation but does not explain each parameter beyond what the schema provides, so it neither harms nor significantly improves 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 states the action ('Create a NEW project'), the target resource, and the distinguishing context ('domain-admin keys only; plan-gated'). It also emphasizes 'fresh app', making the purpose distinct from update/replace tools.

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

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

The description gives clear context: 'Use for a fresh app' and 'NEW project' imply this is not for existing projects. It also notes access and plan restrictions, but it does not explicitly name alternative tools such as build_update_project or build_replace_project.

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 indicate destructive and non-idempotent behavior, and the description adds helpful context about the ephemeral, throwaway nature of the cloud preview. It does not explicitly mention all side effects, but with annotations the bar is lower.

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

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

The description is compact and front-loaded with the main action, but the parenthetical details make it slightly dense. Overall it is efficient and avoids unnecessary fluff.

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

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

The description explains what the tool does and the deployment targets but does not mention what the response contains or potential failure modes. Given the lack of an output schema, some additional return-value context 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 descriptions cover 75% of parameters, and the tool description elaborates on the target parameter. However, project_uuid has no description and is required, so there is a notable gap in parameter-level clarity.

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 deploys a published version, with explicit options for target. It distinguishes itself from build_go_live, which is the alternative for permanent URLs.

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

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

It provides guidance on when to use this tool versus build_go_live and explains the target options and defaults. It could be more explicit about when to prefer local over cloud_ephemeral, but the context is mostly 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?

The readOnlyHint annotation already covers the non-destructive nature, so the description doesn't need to repeat that. It adds valuable behavioral details: it reports elapsed_s and defines a failure condition (pending after ~5 minutes). This informs the agent about timing expectations and error interpretation, which is useful 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 exceptionally concise: two sentences that front-load the purpose, then usage, then behavioral detail. Every sentence adds distinct value with no redundancy. It is well-structured for quick parsing by an agent.

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

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

The tool has no output schema, so the description's mention of 'reports elapsed_s' provides essential return-value context. It also covers the failure condition and usage. Missing details like full response structure or polling interval are minor given the tool's simplicity and the fact that it's a companion to build_deploy/build_go_live. It feels adequately 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 coverage is 50%: poll_url has no description in the schema, but the tool description clarifies it as the URL returned by the deploy tools. This compensates for the missing schema documentation. The permanent parameter is already described in the schema, so the description doesn't need to repeat it. The added clarity for the required parameter earns a 4.

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: to poll a cloud deploy initiated by build_deploy or build_go_live. It specifies the resource (deploy) and the action (poll), and differentiates it from sibling tools like build_e2e_test_status and connector_status. The mention of the two parent tools makes the intent 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 states when to use the tool: after a deploy started by build_deploy or build_go_live, and instructs to pass the returned poll_url. It also provides a critical usage note about treating a pending launch after 5 minutes as failed. However, it doesn't explicitly mention alternatives or when not to use it, though the 'started by' clause provides a clear 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?

Annotations already declare non-readOnly, non-idempotent, non-destructive. The description adds value by explaining the trigger-and-wait behavior, the timeout cap with resume via execution_id, and that the job continues server-side on timeout. It does not contradict 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 sentences, front-loaded with the core action and outputs, then the sequencing constraint. Every sentence earns its place with zero waste.

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

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

For a tool with no output schema, the description explains what it returns and the sequencing. It covers the trigger-wait-resume pattern and the bind constraint. Missing error handling details, but sufficient for an agent to call it correctly given the 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 67% (timeout and execution_id have descriptions, connector_id does not). The description does not add any parameter-specific guidance beyond what the schema already provides, and it fails to compensate for the undocumented connector_id. Adequate but not value-adding.

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 (Discover a connector's schema), names the resource, and lists exact outputs (streams, columns, primary keys, AI-inferred Supero schemas, field mappings, namespace). It differentiates from sibling connector_discover* tools by framing it as a combined trigger-and-wait operation with sequencing hints.

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

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

Explicitly states to run AFTER build_connect_data_source and BEFORE build_bind_data_source, and explains a hard constraint (live bind's source must equal a discovered stream name). This provides clear when-to-use and when-not-to-use context, and distinguishes from the separate connector_discover steps.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, which is ambiguous about side effects. The description calls it a 'PREFLIGHT' and lists checks, implying it analyzes rather than modifies, but it never states whether it produces a report, mutates state, or has side effects. It adds useful context about the checks performed, but does not fully disclose behavioral traits beyond the annotations.

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

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

The description is a single dense paragraph but stays focused. It front-loads the core purpose, then lists concrete failure modes, and ends with a usage directive. Every clause adds value; there is no fluff. It's slightly long but efficient for the information conveyed.

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

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

The tool has no output schema, so the description should explain what the agent can expect as a result. It mentions 'catches' issues but doesn't specify the return format (e.g., a list of problems, a pass/fail status). It also omits prerequisites or side-effect warnings. Given the tool's complexity (preflight checks) and missing output info, the description is incomplete for an agent to fully anticipate the tool's behavior.

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

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

Schema coverage is 100%, and each parameter already has a clear description in the schema. The tool description does not add new semantic meaning beyond what the schema provides (e.g., it doesn't clarify file formats beyond 'Map of {relative_path: file_content}' which is already in the schema). With full schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'PREFLIGHT a bundle BEFORE publish/deploy', and immediately differentiates it from build_validate by enumerating the exact deploy-killer categories it catches. This leaves no ambiguity about what the tool does and how it differs from its sibling.

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

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

It explicitly instructs 'Run it after build_validate and before build_publish', giving a clear temporal placement in the workflow. It also implicitly states when not to use it (i.e., when you've already run build_validate and are ready to publish). This is direct, actionable 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 write behaviour (write-safe on dev, read-only on live), costs (2-4 min compute), and asynchronous nature (returns run_id, poll status). This goes well beyond the simple destructiveHint annotation, giving 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?

The description is a single dense paragraph with many semicolon-separated clauses, but each clause carries unique, necessary information. It is not overly verbose for the amount of caveats covered, though a more structured layout would improve readability.

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

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

It covers all essential context: prerequisites, safety guarantees, operational costs, async handling, and how to poll results. The description is fully self-contained for an agent deciding to call this tool.

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

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

All parameters have schema descriptions (100% coverage), so the baseline applies. The description text does not add extra parameter semantics beyond the schema, so it remains at the baseline level.

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 runs the full behavioural test suite against a published bundle in the project's own deployed app, and distinguishes it from the smoke test. This gives a precise, actionable 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?

It explicitly states when to use it (after build_validate and build_doctor pass, on a deployed and seeded project), when not to (not a per-edit check), and contrasts with the lighter smoke test. This provides clear guidance on selection.

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

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

Annotations only declare readOnlyHint=true. The description goes well beyond: it details behavior while running (status only), when complete (compact report with verdict, per-suite results, findings, next_steps), and on failure (cause). It also discloses an important behavioral guarantee: the verdict is honest and never reports 'healthy' if a core suite couldn't run. This adds significant 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 dense but efficient. It front-loads the purpose, then logically organizes the return behavior: while running, when complete, and on failure. Every sentence conveys necessary information without fluff. The structure flows naturally and avoids 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 complexity (polling with multiple return states) and the absence of an output schema, the description serves as the full spec. It covers all key aspects: running state, completion report contents (verdict, per-suite results, findings, coverage, next steps), and failure behavior. Nothing an agent needs to correctly invoke and interpret the tool 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?

There is only one parameter, run_id, and the schema already provides a complete description ('The run_id from build_e2e_test.') with 100% coverage. The tool description adds no additional meaning about the parameter itself, so it does not exceed the baseline of 3. The schema carries the semantic weight.

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: 'Poll an e2e run started by build_e2e_test.' It identifies a specific verb (poll), resource (e2e run), and explicitly references the sibling tool that initiates the run, distinguishing it from other status tools like build_deploy_status. It also describes what it returns during and after the run, leaving no ambiguity about its function.

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 context by stating it polls a run started by build_e2e_test, making it clear this is a follow-up to that tool. It does not explicitly state when NOT to use it or name alternatives, but the reference to the starting tool provides sufficient guidance. A more explicit exclusion or alternative mention would have earned 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?

The annotation readOnlyHint=true already covers the read-only nature. The description adds transparency about the returned artifact (file list, signed URL, or inline file content) and warns that re-authoring drops hand-authored files. This goes beyond the basic 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?

Two concise sentences. The first sentence front-loads the core purpose, and the second gives critical usage guidance without fluff. No redundancy or filler.

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

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

For a simple fetch operation with no output schema, it sufficiently describes what is returned in both modes. It also adds important context about using the bundle as a starting point. Minor gaps like error handling or output format are not critical given the low complexity.

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

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

Schema coverage is 67%, with descriptions for file and version_uuid. The description enriches the file parameter by explaining that it returns that single file's content inline. The project_uuid parameter is self-evident and not described, but the added file semantics lift the score above 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 states a specific verb and resource: fetch a published bundle, either the file list with a signed download URL or a single file's content via the file parameter. It clearly distinguishes itself from sibling tools like build_get_project and build_stage_bundle.

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 directs the agent to start from this bundle for any change request on an existing app and warns against re-authoring from scratch. It does not name alternative tools explicitly but the when-to-use guidance is clear and actionable.

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

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

Discloses paging behavior (~32KB sections, more:true header, offset usage), default values, and read-only nature. The readOnlyHint annotation is consistent, and the description adds details about response structure and best practices.

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 every sentence serves a purpose: purpose, usage, paging, and file selection. No redundant phrases; structure flows logically from what to do to how to page.

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 (enums, paging, multiple files), the description covers all necessary aspects: how to list archetypes, select one, fetch a file, and paginate. It even explains how to interpret the header, leaving no ambiguity.

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 descriptions cover 100% of parameters with enums and meanings. The description enriches these by explaining the default 'index', how file= narrows output, and how offset/max_bytes control paging, adding practical 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 clearly states the tool fetches a complete production-quality reference app for copying patterns, listing specific files and archetypes. It distinguishes itself from sibling build_* tools by focusing on example retrieval.

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 instructs to use archetype='index' to list options, pick the closest app, fetch BEFORE authoring UI, use file= for single files, and handle paging with offset. Provides actionable steps and warns against re-fetching from 0.

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 aligns with the readOnlyHint: true annotation, indicating a read-only operation. It adds transparency by detailing the exact data returned (namespace, version, project_intent and its subcomponents), which goes beyond the annotation's minimal 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 excessively verbose and repetitive, repeating 'BUILD TO THIS' and using all-caps phrases that add noise. It could be reduced to a few concise sentences without losing any essential information, and the current structure hinders readability.

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

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

Given there is no output schema, the description provides a reasonable overview of the return content (namespace, version, project_intent breakdown). It lacks details on error handling and response format, but the essentials are covered, making it adequate but not exhaustive.

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

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

The sole parameter project_uuid is fully described in the schema ('Project UUID (from build_list_projects)'), and the description does not introduce any additional meaning or constraints. Schema coverage is 100%, so the baseline of 3 applies.

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

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

The description clearly states it retrieves one project's details, listing specific elements like schema_namespace, last published version, and project_intent. However, the heavy repetition and capitalization ('BUILD TO THIS') obscure the core purpose and make it less crisp than it could be.

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 does not explicitly guide when to use this tool over any sibling tools (e.g., build_list_projects for multiple projects, build_get_bundle for bundles). It implies a single-project lookup but lacks direct alternative comparisons or conditions.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict this. The description adds significant behavioral context beyond the annotation: it details what the tool returns (state machine, operations, schemas, UI schemas) and emphasizes that it is the 'bulletproof reference.' It does not mention potential errors or performance, but for a read-only tool, this is sufficient. The description adds value over 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 carries value: it states the purpose, enumerates services, lists return contents, gives a strong usage directive, and explains defaults. It is front-loaded with the core purpose. The redundancy in 'ALWAYS call' and 'do not guess' reinforces but is not excessive. Structure is logical, moving from purpose to content to usage. It could be slightly tighter, but it earns a 4.

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 (multiple return components, no output schema), the description is fairly complete: it explains what is returned and when to use it. It does not describe error handling or output format details, but for a read-only contract fetch with well-defined parameters, this is adequate. The description covers the essential information an agent needs to call the tool correctly.

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

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

Schema description coverage is 100%, so the input schema already documents both parameters with descriptions. The description adds minor clarifications: it mentions service_id='index' default and gives examples of service IDs, and it explains the parts parameter's meaning ('contract' vs 'ui_schemas'). However, this largely duplicates the schema descriptions. Since the schema does the heavy lifting, the description adds limited new semantic value, meriting the baseline score of 3.

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

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

The description clearly states the verb 'Fetch' and the specific resource: the authoritative contract for transactional/stateful platform services. It enumerates service types and explicitly lists what is returned (state machine, operations, schemas, UI schemas), making it unambiguous. It distinguishes itself from sibling tools like build_get_bundle or build_get_project by focusing on service contracts, so an agent can easily differentiate 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 provides explicit usage instructions: 'ALWAYS call this for any service your app `extends` BEFORE authoring its UI' and warns against guessing. It also explains the default behavior of service_id='index' and the parts parameter. This is clear when-to-use guidance and implies when not to use it (e.g., when not extending a service). It does not name specific alternatives, but the instruction is strong enough to route the agent correctly.

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

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

The description discloses read-only behavior aligned with the readOnlyHint annotation, and goes beyond by explaining what the tool returns (doc + content version + SDK floor) and how paging works. It does not mention error conditions or rate limits, but those are not essential given the simple read operation and existing 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 somewhat long, but every sentence carries meaningful guidance—defaults, paging behavior, and reading order. The structure is front-loaded with the core purpose and then flows naturally into the enum explanation and paging instructions. Minor redundancy exists (e.g., repeating the read-order advice), but it does not detract from usability.

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 absence of an output schema, the description compensates by describing the return payload (doc + content version + SDK floor) and the paging protocol. It also covers all 12 enum options, explains the special 'skills' default, and ties the tool into a larger workflow. There are no critical gaps for an agent deciding whether and how to invoke it.

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

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

The schema description already covers all three parameters with 100% coverage, and the tool description adds valuable context: it clarifies the default for 'doc' ('skills'), the meaning of 'offset' for byte-based paging, the default for 'max_bytes' (~32000), and the semantics of each enum value. This exceeds what the structured schema alone provides.

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

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

The description clearly states the tool's purpose as fetching a Supero build reference, using the specific verb 'Fetch' and naming the resource ('build reference'). It also enumerates the distinct document types available, distinguishing it from other build_* sibling tools that operate on projects, deployments, or bundles.

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 usage guidance, including a recommended reading order ('Read 'skills' FIRST, then 'components' + a matching build_get_examples before you author UI') and paging instructions ('when the header says more:true, fetch the next section with offset=<next_offset>'). It also explains the rollup of doc types (e.g., 'landing' derives from compact landing pages) and the meaning of the default values.

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 complements the annotations by stressing permanence, noting that build_teardown removes the deployment, and mentioning required permissions. This gives the agent a clear picture of side effects and lifecycle behavior beyond the raw destructiveHint flag.

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?

Every sentence contributes meaningful information: purpose, contrast, defaults, return values, follow-up actions, teardown, and prerequisites. The formatting is clear and there is no fluff, despite the repeated emphasis on 'PERMANENT'.

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

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

Given no output schema, the description explains the return values (public_url and poll_url) and next steps. It also mentions required permissions. It stops short of fully clarifying the interplay between file_id and version_uuid, but overall provides enough context for an agent to act.

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 descriptions cover 67% of parameters; the description adds useful default behavior for version_uuid and file_id. However, project_uuid is not explained beyond its name, and the relationship between file_id and version_uuid remains somewhat implicit.

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 action ('PERMANENT deploy') and distinguishes this tool from the sibling build_deploy(target='cloud_ephemeral') by emphasizing permanence and the public URL. It also references related follow-up tools, making the 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?

It explicitly contrasts with the ephemeral alternative, explains default behavior when version_uuid/file_id are omitted, and provides a clear workflow: poll with build_deploy_status, then smoke test. It also states prerequisites (admin API key and platform enablement), leaving no ambiguity about when and how 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 provide readOnlyHint=true, so the safety profile is covered. The description adds context about classification categories (access modes) but doesn't disclose any additional behavioral traits beyond that. Given the annotation, a 3 is appropriate as the description adds some value but not rich behavioral detail.

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

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

Two sentences with no redundancy. The action is front-loaded and the use case is succinctly stated. Perfectly concise and well-structured.

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

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

The description explains the output at a high level (classifies schemas and access modes), which is enough for an agent to understand the tool's purpose. Since there's no output schema, it doesn't provide exact return structure, but given the tool's simplicity and the annotations, this 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?

The single parameter project_uuid is fully described in the schema ('Defaults to the key's project'), achieving 100% coverage. The description adds no extra parameter semantics, so the baseline 3 applies.

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

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

The description clearly states the tool classifies schemas by connector-backed vs app-authored and access mode. It distinguishes from sibling tools like schema_list or schema_get by focusing on classification and access modes, and provides a specific use case that differentiates 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 explicitly says when to use it: to avoid rendering create/edit UI for read-only live sources or overwriting connector-discovered schemas. It doesn't name alternative tools, but the use case is clearly scoped, giving strong guidance on when this tool 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?

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds meaningful behavioral context: it returns exact service IDs, categories, key requirements, and permissions, and emphasizes the 'LIVE catalog' and 'never guess a service id'. This enriches the agent's understanding of what the tool does beyond the annotation. No contradictions found.

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

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

The description is detailed but not bloated; each sentence serves a purpose, and the main purpose is front-loaded. It includes examples and usage notes, which are useful. It could be trimmed slightly (e.g., the long parenthetical list), but overall it is well-structured 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?

With no output schema, the description effectively explains the return contents (service_id, category, key need, permissions) and how to apply them (use verbatim in config.py). It covers both parameters' behavior and clearly sets expectations. For a read-only listing tool, this is comprehensive and leaves no major gaps for an agent to call it correctly.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description reinforces the effect of service_id ('Pass service_id for one service's config fields') and clarifies the category filter is optional. While this adds a little nuance, it does not significantly exceed what the schema already provides, so a baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('List') and resource ('platform's available services/integrations from the LIVE catalog'), with concrete examples. It distinguishes itself from siblings by explicitly saying 'Descriptive — what EXISTS, never what to use', which sets it apart from recommendation or configuration tools. The purpose 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?

It specifies when to use the tool ('so the intake's question is accurate') and what not to do ('never what to use'), which is a clear exclusion. It also gives guidance on the optional service_id parameter ('Pass service_id for one service's config fields'). However, it does not explicitly name an alternative tool (e.g., build_recommend_integrations) for the 'what to use' scenario, though the exclusion is strong.

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

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

The annotation readOnlyHint=true already signals a non-mutating operation, and the description does not contradict that. The description adds value by detailing what types of data sources are included (own DBs, REST, warehouses, public API catalog) and how the tool fits into the overall connection flow. This goes beyond the annotation without repeating it.

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

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

The description is moderately long but every sentence earns its place: it lists categories, mentions the curated catalog, gives a use case, and provides flow context. The most important content (what is listed) is front-loaded. It could be slightly tightened, but it is efficient and well-organized for a tool with no parameters.

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 is a simple list operation with no parameters and a read-only annotation, the description is thorough: it specifies the exact scope of data sources, the intended use case, and related tools. It does not explain return format, but for a list tool with no schema this is acceptable; an agent can infer it returns a list of names/types. 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?

The tool has zero parameters, so there is nothing for the description to clarify. The schema is empty and fully covered by definition. The description explains the output content (list of data source types), which is more useful than any parameter detail. Baseline for 0 params is 4, and the description fully compensates by describing the result.

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 a precise resource ('external DATA SOURCE types an app can connect to'), enumerating concrete examples (Postgres, REST API, warehouses) and a curated catalog. It clearly distinguishes itself from siblings like build_connect_data_source and build_discover_source by focusing on enumeration of available source types, and even references the flow to contextualize 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?

It explicitly says when to use it: 'Read this to offer a connect your own data option.' It also gives the flow (build_connect_data_source → build_discover_source → build_bind_data_source) and points to build_get_skills for further info. However, it does not explicitly state when not to use it or mention alternative tools that might replace it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the return fields but does not disclose additional behavioral aspects such as pagination, rate limits, authentication requirements, or side effects. Since the bar is lower with annotations, a score of 3 is appropriate—the description is consistent and does not contradict annotations, but it adds minimal extra 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 a single sentence that front-loads the core action and includes the return fields in parentheses. There is zero wasted text, and the information is presented in an efficient, scannable manner. It is appropriately concise for a simple list tool.

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

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

For a simple list operation with one optional parameter and no output schema, the description covers the essential purpose and return fields. It implies the scope ('you can build into') and provides the output structure. It does not mention pagination or ordering, but these are minor for a straightforward list call. The description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100% for the single parameter 'limit' (Max results, default 50). The description does not add any meaning beyond what the schema provides. Given high schema coverage, the baseline of 3 is correct—the description is not required to compensate, and it does not.

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

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

The description states a clear verb and resource: 'List projects you can build into' and enumerates the returned fields (uuid, name, schema_namespace, live_url). It distinguishes itself from sibling tools like build_get_project (which likely retrieves a single project) and build_list_bound_schemas (which lists schemas) by clarifying the scope as buildable projects. The purpose is unambiguous and specific.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention build_get_project for details, build_create_project for creation, or any exclusions. While the purpose implies listing projects, there is no explicit when-to-use or when-not-to-use guidance, which is a gap given the large 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?

Discloses read-only behavior (matching readOnlyHint) and adds the rate-limited-per-domain constraint beyond the annotations. It doesn't mention error handling, empty result behavior, or log retention, but the key side-effect-free nature is 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?

Two tight sentences with strong front-loading: the primary action first, followed by usage context and constraints. Every clause 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?

For a tool with no output schema, the description adequately covers what it does, when to use it, and its constraints. It doesn't describe the return format or log content shape, but given the tool's simple nature and the presence of sibling status/doctor tools, the provided context is sufficient.

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

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

Schema descriptions for lines (max lines, default 200) and since (minutes back, default 60) are clear, but project_uuid has no description and the tool description adds no parameter clarification beyond the schema. 67% schema coverage sits below the high threshold, leaving a notable gap.

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

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

States a specific verb (Fetch), a clear resource (Cloud Run logs), and a scoped subject (project's deployed app). The phrase 'THE tool for diagnosing a failed/stalled cloud deploy or a crashing app' strongly distinguishes its intended purpose from sibling build_* 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 states when to use it — for diagnosing failed/stalled deploys or crashing apps — and provides concrete examples (startup-probe timeouts, tracebacks, 'container failed to start on PORT'). It doesn't explicitly name sibling alternatives like build_deploy_status or build_doctor, but the diagnostic framing gives clear when-to-use 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 readOnlyHint annotation already covers non-mutating behavior, and the description adds transparency by stating the tool is deterministic and returns a checklist rather than performing actions. No contradictions exist, though more detail about failure modes or empty inputs would improve 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 informative but somewhat verbose, with repetitive emphasis on planning first and the rationale behind it. It could be tightened while retaining the key sequencing and output 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?

Even without an output schema, the description enumerates the main return elements (build checklist, page structure, terminology, detail-page determination, multi-tenant login pattern, seed guidance, examples to copy). This gives the agent a solid expectation of what will be provided, though explicit output formatting is not described.

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 descriptions cover all four parameters at 100%, so the tool description does not need to add much. It does add context around how entities, public_facing, and is_multi_tenant affect the returned guidance, but those nuances are already present in the input 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's purpose: turning an app idea into an explicit build checklist. It names the specific outputs (page structure, terminology, detail-page guidance, multi-tenant login pattern, seed guidance, examples to copy) and distinguishes it from related build tools by specifying it should be called after build_get_skills and before authoring.

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 sequence: 'Call it right after build_get_skills and BEFORE authoring.' It also clarifies the tool is deterministic and not LLM-based, which helps agents choose it appropriately among similar build_* tools.

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

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

Annotations already indicate non-read-only and non-destructive. The description adds useful behavior: it runs build_validate first unless force=true, and it returns artifact identifiers. This gives the agent a clear expectation of side effects without contradicting the annotations.

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

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

The description is very concise, using compact symbols and a few sentences to cover the main action, return values, validation behavior, and the three file-providing options. No unnecessary filler or redundant repetition of schema 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?

Given the tool's purpose, the description covers all critical aspects: what it does, what it returns, the validation flow, and the various input methods. It omits edge cases like error handling or prerequisites, but these are not essential for an agent to successfully 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?

The schema already documents most parameters explicitly (files, force, app_type, validate, files_ref, files_b64gz), with project_uuid missing a description. The description adds extra context for files_ref and clarifies the file map format, which goes beyond the schema's existing notes.

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: package, upload, and record a version under the project. It also mentions the return values (version_uuid, file_id, download_url) and the validation step, which distinguishes it from staging and deployment 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 explains internal options (files, files_b64gz, files_ref) and when to prefer one over another, but it does not explicitly tell the agent when to use this tool versus siblings like build_stage_bundle or build_deploy. It only implies that this is the publish step.

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 readOnlyHint=true, and the description adds substantial behavioral context: it is deterministic, draws only from live installed manifests, returns grouped/tiered suggestions with default options flagged, and cannot suggest providers not installed. This goes beyond the annotation's safety signal and gives the agent a realistic model of the tool's behavior.

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

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

The description is dense but every sentence serves a purpose: it states the core function, explains the mechanism, gives concrete examples, and distinguishes from a sibling. It is front-loaded with the primary action and maintains focus. Slightly long but not wasteful.

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 recommendation tool with no output schema, the description explains the output format (grouped, tiered, with default flagged), the input constraints (live manifests only), and the relationship to a sibling tool. It covers all the information an agent needs to invoke it correctly and interpret results.

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

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

Schema coverage is 100%, so both parameters are documented. The description enriches their semantics by explaining how each drives recommendations: 'description' drives email/sms/oauth/ai/payment triggers, and 'service_ids' drives most recommendations, with examples like ['cart','order']. This adds meaning beyond the schema's basic field 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 ('RECOMMEND') and resource ('concrete provider integrations') and clearly differentiates from sibling build_list_capabilities by labeling itself as prescriptive versus descriptive. It gives concrete examples of what it returns, so an agent can unambiguously understand its 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?

Explicitly tells when to use this tool versus build_list_capabilities: 'call this so you don't OMIT a needed integration; use build_list_capabilities for a service's exact id + config fields.' Also provides usage context with examples like cart/checkout requiring a payment gateway.

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 destructiveHint=true, but the description adds critical detail: what data is wiped versus retained (credentials, API keys, namespace, tenant), the validation order (bad bundle is a no-op), and the post-wipe publish step. This goes far beyond the annotation's binary flag and fully discloses the tool's behavior and 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 dense but well-organized. It front-loads the destructive warning and conditions, then explains the validation order and post-action. Every sentence adds value: the retention details, the mode restriction, the validation safety, and the build_publish reference. There is no redundancy, and the structure leads the reader from warning to conditions to workflow.

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

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

For a destructive, multi-step tool with 6 parameters, the description covers all essential aspects: purpose, prerequisites, safety confirmation, validation behavior, and the next step (build_publish). It also mentions files_ref for large bundles, addressing a common constraint. Even without an output schema, the description is sufficient for an agent to invoke the tool correctly and understand the consequences.

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 67%, and the description enriches the two key parameters: confirm_project_name (safety confirmation) and files (validated before wipe). However, app_type has no schema description and the description doesn't mention it, leaving that parameter underdocumented. For the critical parameters, the description adds significant meaning beyond the schema, but the gap for app_type prevents a perfect score.

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: 'completely replace a DEV-mode project's app' with explicit destructive semantics. It specifies the resource (project's app), the scope (DEV-mode only), and the safety condition (confirm_project_name). It distinguishes itself from sibling tools like build_update_project and build_publish by emphasizing the wipe-and-replace nature, 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 explicit usage conditions: 'DOMAIN-admin keys only', 'Refused if mode='live'', and the requirement for confirm_project_name. It also explains the conditional workflow: if files are passed, they are validated before wipe and published after; otherwise wipe-only then call build_publish. This gives clear guidance on when to use and what to expect, including the fallback to build_publish.

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. The description adds valuable context: MCP-created connectors are trigger:manual, so sync bindings copy no rows until a run executes, and it returns a run id. It does not contradict annotations and discloses the manual-trigger behavior that is not obvious from schema alone.

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

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

Two concise sentences. The first states the core action and return value, the second provides essential context and sequencing. No redundant words, and the most critical information is front-loaded.

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

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

For a single-parameter tool with no output schema, the description covers everything an agent needs: what it does, when to call it, the manual-trigger nuance, and the alternative for live-read bindings. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, and the parameter description already specifies 'The connector to run (from build_connect_data_source)'. The tool description reinforces the source of the connector but adds no new syntax or format details beyond the schema. Baseline 3 is appropriate given full schema documentation.

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 ('Trigger a SYNC RUN') and a resource ('data connector'), and explicitly returns the run id. It distinguishes itself from sibling tools like build_bind_data_source (binding) and connector_run by clarifying it executes a sync run rather than other operations. The purpose 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?

Explicitly instructs when to call: 'after build_bind_data_source (and again whenever the source data changes)'. It also specifies when NOT to use it: 'Live-read/warehouse bindings don't need runs (they read the source directly)'. This clearly differentiates from alternatives and gives a sequence.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds valuable context by explaining that dev mode allows COMPLETE REPLACE (wipe data, keep credentials) and live protects it, which clarifies the destructive nature and its limits. This goes beyond the annotation flags.

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

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

Two concise sentences: the first states the purpose, the second provides usage guidance. The most important information (mode semantics) is front-loaded, and every sentence contributes value 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?

For a simple mode-setting tool with no output schema and two parameters, the description covers the essential aspects: what it does, the modes, and usage context. It does not mention return values or side effects beyond data handling, but given the simplicity, it is adequately 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 has only an enum for 'mode' and a generic 'project_uuid'. The description explains the meaning of 'dev' and 'live' values, adding semantic depth beyond the enum names. project_uuid is self-evident. With 0% schema coverage, the description compensates well for the critical 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 states the verb 'Set' and the resource 'project's build mode', and explains the two modes 'dev' and 'live' with their distinct implications. It effectively distinguishes itself from sibling tools like build_deploy or build_replace_project by focusing on the mode configuration.

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 guidance on when to use dev ('Switch to dev before replacing') and when to use live ('to live when it's in production'). It implies the tool is used when adjusting build mode, but does not explicitly mention alternatives or when not to use it, though the context is clear.

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

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

Annotations declare readOnlyHint=true, and the description goes well beyond that by detailing the exact HTTP checks, the behavior with expected_app_js_sha1 (including that malformed values are warnings, never false mismatches), and the optional login/data-read flow. This gives an agent a precise picture of what the tool inspects and how it reports.

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 but every sentence contributes: it states the purpose, lists the checks, gives usage guidance, and ends with an emphatic usage directive. The structure is front-loaded with the main verb and resource, and the key usage note is placed at the end for emphasis.

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

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

The description thoroughly covers what the tool does and when to use it, but it does not specify what the tool returns or how the agent should interpret the results (e.g., success/failure details, exit codes). Since there is no output schema, this missing return-value information leaves a gap for an agent deciding how to act on the outcome.

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

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

Schema already documents all 8 parameters (100% coverage), but the description adds important context for several: url is sourced from build_deploy_status, poll_url is an alternative, and expected_app_js_sha1 is explained in terms of its purpose (confirming the deploy rolled vs a stale cache). This goes beyond the schema's individual parameter descriptions.

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

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

The description opens with a clear, specific verb ('VERIFY') and resource ('a DEPLOYED app actually works'), and enumerates concrete checks (root title, app.js bundle, config namespace, optional login/data read). This distinguishes it from siblings like build_e2e_test (which runs full E2E) and build_deploy_status (which only checks deployment state).

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 frames the tool as 'THE post-deploy gate — run it after every deploy,' and tells the caller to pass url= from build_deploy_status or poll_url=. It doesn't name an alternative to avoid, but the post-deploy context and the distinction from build_e2e_test is clear enough.

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

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

The annotations already mark readOnlyHint=true, and the description adds valuable behavioral context: it returns an endpoint, requires an out-of-band upload with the user's own key, and explains how the file_id is consumed. It doesn't contradict annotations and provides meaningful operational detail beyond the structured 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 three sentences, each earning its place: the first states the purpose and the token-cap motivation, the second gives the upload instructions, and the third ties the result to downstream tools. It is front-loaded with the core purpose and avoids fluff.

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

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

For a zero-parameter, read-only tool with no output schema, the description fully explains what it does, why it exists, how to use it, and what to do with the result. An agent has everything needed to invoke it correctly and integrate it with the rest of the workflow.

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 zero parameters, the schema trivially covers all parameters (100% coverage), so the baseline is 4. The description adds no parameter details (there are none) but explains the return value (endpoint and file_id) and the expected input format for the upload (gzip of json {path:content}), which is useful 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 ('get the out-of-band UPLOAD endpoint') and resource ('for a LARGE app bundle'), and clearly explains its role relative to sibling tools like build_validate and build_publish. It distinguishes itself as the staging step for large bundles that cannot fit inline, which is a unique and 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?

It explicitly states when to use it ('for a LARGE app bundle that won't fit inline'), contrasts with truncation/minification as the alternative, and provides a precise workflow: upload a gzip blob to the returned URL, then pass the file_id as files_ref to specific downstream tools. This gives an agent clear guidance on when and how to invoke 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 mark it destructive and idempotent, but the description adds crucial details: it deletes both permanent and preview services, frees URLs, refuses non-Supero projects, explains the stopped flag meaning, warns about incomplete teardown and billing, and requires a specific admin key. This is far beyond annotation coverage and provides rich behavioral context with no contradictions.

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

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

The description is dense but every sentence earns its place: main action first, then scope, then idempotency, then constraints, then operational guidance, then auth. No fluff; it is front-loaded and efficiently structured.

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

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

The tool is destructive and has special conditions, and the description covers all necessary aspects: what it does, what it deletes, idempotency, scope limitation, error behavior, how to interpret the stopped return flag, and authentication requirements. With no output schema, the description fully equips an agent to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate for the single parameter project_uuid. It implies the parameter by saying 'a project's live deployment' but never explicitly names it or explains its format/constraints. Since the tool has only one obvious parameter, this is adequate but not explicit, so a 3 is appropriate.

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

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

The description uses a specific verb ('tear down') and a clear resource ('a project's live deployment'), explicitly states it deletes Cloud Run services and frees URLs, and differentiates from build_go_live by mentioning both permanent and ephemeral apps. It is immediately distinguishable from siblings 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 clearly states the scope (only Supero-hosted apps), the idempotent behavior, and the condition for re-running (stopped=false). It implies this is the teardown counterpart to build_go_live, but it does not explicitly name alternative tools or state when to prefer them. It gives strong situational guidance but lacks explicit exclusion statements.

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 idempotentHint=true, so the description doesn't need to restate safety. It adds value by listing the specific updatable fields, which is not in the schema. However, it doesn't explicitly state that it's a partial patch (only provided fields change), though the parameter name 'patch' implies it. This is adequate given 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 a single, front-loaded sentence that immediately states the action and scope. There is no wasted wording, and the key information (verb, resource, fields) is delivered efficiently.

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 update tool with only two parameters and no output schema, the description covers the essential behavior. It doesn't explain return values or prerequisites, but annotations cover safety and the patch semantics are implied by the parameter name. The tool is moderately complex, and the description is sufficiently 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 describes patch as 'Fields to update.' with 50% coverage (project_uuid has no description). The description compensates by enumerating the exact fields (display_name, description, show_public, live_url), giving agents concrete knowledge of what can be patched. This goes beyond the schema and improves 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 uses a specific verb ('Update') and names the exact resource ('project') plus enumerates the metadata fields (display_name, description, show_public, live_url). This clearly differentiates it from sibling tools like build_create_project and build_replace_project, which are distinct 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 this tool is for modifying existing project metadata, but it does not explicitly state when to use it over alternatives like build_replace_project or build_create_project. The context is clear from the verb and fields, but no exclusions or alternative recommendations are 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?

Beyond annotations (which only mark readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description adds a key safety guarantee: 'AST-only (your code is never executed)'. It also details the scope of checks. This meaningfully supplements the annotations, though it does not describe the return format or any side effects (e.g., does it write logs?).

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, well-structured sentence that front-loads the primary action and timing, then lists the specific validation categories in a compact list. Every word contributes value; there is no fluff or repetition.

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

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

For a validation tool with no output schema, the description covers the main usage, safety, and scope. It does not state what the response looks like (e.g., a report of errors), which could be helpful, but the absence is not critical since the purpose is clear and the tool's behavior is predictable. Given the complexity (4 params, nested objects), it is reasonably complete.

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

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

Schema description coverage is 100% – every parameter is already documented in the input schema. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies. It does hint at the namespace check tying to project_uuid, but that is not a substantial addition.

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 verb (validate), the resource (locally-authored bundle), and the timing (BEFORE publishing). It enumerates the specific checks (manifest, syntax, import-safety, config exports, schema validity, namespace) which differentiates it from siblings like build_deploy or schema_validate.

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 positions the tool as a pre-publish validation step ('BEFORE publishing'), giving clear context on when to use it. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can infer when it 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?

The readOnlyHint annotation covers safety, and the description transparently lists the information returned. No side effects or hidden behaviors are implied, and the description aligns with 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 a single, focused sentence that states purpose and return contents without unnecessary detail. It is well structured and easy 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?

The description fully explains what the tool does, what it returns, and when to use it. In the absence of an output schema, the listed fields provide sufficient context for an agent to understand the result.

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

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

There are no parameters, so the baseline of 4 applies. The description does not need to explain parameter semantics.

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

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

The description clearly states the tool resolves the API key's scope, enumerates specific details (role, domain, project creation ability, plan), and suggests using it to decide flow. This is a specific verb and resource, distinct from other 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 a clear usage trigger ('Call this to decide the flow') but does not explicitly mention alternatives or when not to use it. This is slightly less than fully explicit but still useful.

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 idempotentHint=true, and the description's 'cancel' is consistent with these. However, the description adds no further context about the effect on the execution (e.g., whether it's asynchronous, reversible, or what happens to related resources). Given the annotations cover the safety profile, the description is adequate but 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?

A single, concise sentence with no filler. The verb 'Cancel' is front-loaded, and the resource is specified clearly. 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 simple cancel operation with two fully described parameters and annotations covering idempotency and destructiveness, the description is sufficient for an agent to know what to do. There is no output schema, so return values aren't expected. A minor gap is that it doesn't mention potential failure modes (e.g., canceling an already-completed execution), but that's not critical.

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 provides clear descriptions for both parameters (connector_id and execution_id) with 100% coverage. The description adds no additional parameter information, so it relies entirely on the schema. Baseline of 3 is appropriate when the schema fully documents parameters.

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

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

The description 'Cancel a running connector execution' states a specific verb (cancel) and resource (connector execution), clearly distinguishing it from sibling tools like connector_run and connector_status. The action is unambiguous and instantly understood.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that it should be used to stop an execution that is no longer needed, nor does it reference any sibling tools or conditions for cancellation. An agent would have to infer the context from the tool 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?

Annotations already declare idempotentHint=true and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context (e.g., effect on running jobs, reversibility) beyond the action itself, but it does not contradict 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 a single, direct sentence with zero waste. The action is front-loaded and unambiguous.

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

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

With one well-documented parameter and annotations covering safety, the description is minimally adequate. However, it omits the practical effect of disabling (e.g., stops future runs) and does not reference the sibling connector_enable, leaving some context 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 100%, and the single parameter connector_id is described as 'UUID of the connector.' The description adds nothing beyond what the schema already documents, so the baseline of 3 applies.

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

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

The description states a clear verb and resource ('Disable a connector') that is distinct from siblings like connector_enable. However, it lacks specificity about what disabling entails (e.g., prevents new runs, preserves configuration), so it stops short of the richest possible clarity.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention the counterpart connector_enable or any conditions for disabling, leaving the agent to infer usage context.

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

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

Annotations indicate readOnlyHint=false and idempotentHint=false, implying a non-idempotent mutation, but the description adds no behavioral detail. It doesn't disclose whether discovery is synchronous or asynchronous, what state changes occur, or whether results are retrievable via connector_discover_status. The description carries little beyond the annotation 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 a single, focused sentence that immediately conveys the core action. No filler or redundancy; it is appropriately sized for its purpose.

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

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

The tool triggers an action but lacks explanation of expected outcome, async behavior, or follow-up steps (e.g., polling status). With no output schema and no guidance on the params object, an agent cannot fully anticipate the tool's behavior or how to use results.

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

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

Schema description coverage is 100% for both parameters: connector_id is described as 'UUID of the connector' and params as 'Optional discovery parameters'. The description adds no additional meaning, so the baseline of 3 applies given the high coverage.

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

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

The description clearly states the action ('Trigger') and the resource ('schema/metadata discovery') for a specific connector. It distinguishes from siblings like connector_discover_status and connector_discover_results by implying it initiates rather than retrieves, though it doesn't explicitly name the 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?

No guidance is given on when to use this tool versus connector_run, connector_test, or other connector operations. There is no mention of prerequisites, typical invocation context, or 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 annotation readOnlyHint=true already declares this is a read-only operation, so the description does not need to restate that. However, the description adds no additional behavioral context, such as what happens if the execution is not found, whether results are paginated, or what the response structure is. It neither contradicts the annotation nor adds meaningful transparency beyond it.

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

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

The description is a single sentence with no unnecessary words, which is concise. However, it lacks any structural elements such as usage notes or exclusions that would make it more informative. It is not bloated, but it is also not optimally structured to convey essential context.

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 retrieval tool with two UUID parameters and no output schema, the description is adequate but minimal. It tells the agent what the tool does but not when to use it, what the results contain, or any edge cases. Given the low complexity and the presence of a readOnlyHint, it is sufficient for a basic call but lacks the guidance a more complex tool would need.

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

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

The schema already provides full descriptions for both parameters (connector_id as 'UUID of the connector' and execution_id as 'UUID of the discovery execution'), with 100% coverage. The description adds no further detail about the parameters, so it does not enhance what the schema already documents. Baseline of 3 is appropriate.

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

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

The description states a clear verb ('Get') and a specific resource ('discovery results'), which aligns with the parameters connector_id and execution_id. However, it does not distinguish this tool from the sibling connector_discover_status, which also relates to discovery executions. The purpose is clear but not 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 provides no guidance on when to use this tool versus alternatives. It does not mention that it should be used after connector_discover or connector_discover_status, nor does it note any prerequisites or sequencing. An agent is left to infer usage from the name and parameters.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds no extra behavioral context—no polling behavior, error handling, or status values. It essentially restates the name without enriching the agent's understanding of the operation's behavior.

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

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

The description is a single, direct sentence with no extraneous words. It is front-loaded and efficient, though it could arguably be slightly more informative without losing conciseness.

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

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

There is no output schema, so the description should explain what the tool returns, but it does not. It also fails to mention any dependency on a prior discovery call or the nature of statuses. For a status tool, this is a significant gap—an agent cannot anticipate the response format or state transitions.

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 both parameters described (UUID of connector, UUID of discovery execution). The description does not add any additional meaning about the parameters, but the schema already provides sufficient detail, so the baseline of 3 applies.

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

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

The description states a clear verb ('Get') and a specific resource ('discovery execution status'). It is distinct from siblings like 'connector_status' (general connector status) and 'connector_discover_results' (results), though it doesn't explicitly differentiate them. The purpose is clear 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?

There is no guidance on when to use this tool versus alternatives. No mention of prerequisites (e.g., that a discovery execution must be initiated first) or exclusions. The agent must infer from the name and parameters that this is for checking status after a discovery, but no explicit context is 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 already indicate idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description does not contradict these but also does not add extra context (e.g., side effects on scheduling or existing runs). Given the annotations cover the basics, a neutral score is appropriate.

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

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

The description is a single, succinct sentence with no unnecessary words or repetition. It efficiently conveys the core action and 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?

For a simple enable action with one parameter, the description is sufficiently complete. It states what the tool does and its purpose, and the schema covers the parameter. Given the low complexity, no additional context is strictly necessary, though mentioning alternatives 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?

The only parameter, connector_id, is already described in the schema as 'UUID of the connector.' The tool description adds no further meaning or constraints, so it relies entirely on the schema for 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 states the action ('Enable a connector') and its purpose ('for scheduling'), distinguishing it from sibling tools like connector_disable. However, it could be more specific about the exact effect of enabling, such as making the connector available for scheduled runs.

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 minimal guidance on when to use this tool versus alternatives like connector_disable. It does not mention prerequisites (e.g., configuring the connector first) or contrast with related actions, leaving the usage context largely implicit.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds no further behavioral context (e.g., output format, pagination, or ordering). For a simple zero-parameter listing tool, this is acceptable but not particularly informative.

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

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

The description is a single, front-loaded sentence with no wasted words. It is as concise as possible while still conveying the core 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?

Given the tool's simplicity (no parameters, no output schema, read-only annotation), the description is adequate. An agent can infer that it returns a list of plugin identifiers or names. No critical information is missing for a trivial listing operation.

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?

There are zero parameters, so the schema coverage is 100% by default. The description does not need to explain any parameters. Baseline for 0 parameters is 4, which is appropriate here.

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 (List) and resource (available connector plugins), which is specific enough to distinguish from the many other connector operations like connector_run or connector_discover. However, it does not explicitly differentiate from similar listing tools such as connector_discover_results or schema_list, so it misses sibling 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?

No guidance is provided on when to use this tool versus alternatives. The description simply states what it does without any context on use cases, prerequisites, or when another listing tool would be more 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds little beyond stating it's a 'manual sync execution' – it doesn't disclose potential side effects, whether it's asynchronous, or whether it returns a job ID. Given the presence of annotations, the bar is lower, but the description still fails to add meaningful 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?

A single, front-loaded sentence with zero fluff. It immediately communicates the action without 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?

The tool is a mutation with a nested params object and no output schema, yet the description does not explain what happens after triggering (e.g., returns a run ID, is asynchronous, requires connector to be configured). It is too thin for an agent to confidently invoke it correctly.

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

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

Schema description coverage is 100%, with both parameters (connector_id and params) already described. The description adds no extra meaning to the parameters, so baseline 3 applies.

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

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

The description states a specific verb ('Trigger') and resource ('manual connector sync execution'), making the core purpose clear. It distinguishes from siblings like connector_test or connector_status, but does not explicitly name an alternative or contrast, so it's not a perfect 5.

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

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

No guidance on when to use this tool versus connector_enable, connector_test, or connector_discover. The description provides no context about prerequisites (e.g., connector must be enabled) or scenarios where a manual sync 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?

The annotations declare readOnlyHint: true, and the description's 'Get' verb is consistent with a read-only operation. The description does not add extra behavioral details, but given the annotation, it is sufficient. 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, clear sentence with no extraneous words. It efficiently conveys the tool's purpose, making it easy 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?

The description gives a basic idea of the tool's function, but it does not elaborate on the output format or provide usage context relative to other status-related tools. For a simple read-only status endpoint, this may be sufficient, but it leaves some ambiguity.

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 a description for the connector_id parameter ('UUID of the connector'), so the parameter semantics are already covered. The description does not add additional context about the parameter, maintaining a neutral but adequate level.

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

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

The description clearly states the tool retrieves connector status and recent executions, using a specific verb and resource. It is concise and unambiguous, though it does not explicitly differentiate from sibling tools like connector_discover_status.

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

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

The description provides no guidance on when to use this tool over alternatives. It lacks any conditions or scenarios for selection, leaving the agent without contextual hints for tool 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?

The readOnlyHint annotation already declares this as a safe read operation, so the description need not repeat that. However, the description adds no behavioral context beyond the annotation—it doesn't explain what 'testing connectivity' entails, whether it performs a live network call, what happens on failure, or what the return value looks like. With no output schema and minimal description, an agent lacks insight into the tool's actual behavior.

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

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

The description is a single, tightly worded sentence that is front-loaded with the core action. It contains no filler or redundant information, making it maximally concise and easy 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?

For a simple one-parameter tool with a readOnlyHint, the description covers the basic purpose. However, it omits any indication of the output or result (e.g., success/failure indication) and does not distinguish itself from the similar sibling connector_test_config. Given the ambiguity among sibling tools and the absence of an output schema, the description is only minimally 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?

The schema includes a single parameter, connector_id, with a clear description ('UUID of the connector.'), providing 100% schema description coverage. The tool description adds no additional meaning about the parameter—it does not clarify the expected format or how the ID is used. Given full schema coverage, a baseline of 3 is appropriate; the description neither compensates nor detracts.

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

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

The description states a clear verb-resource pair: 'Test an existing connector's connectivity.' It is specific about the action (testing connectivity) and the resource (existing connector). While there are sibling connector tools, the description's focus on 'connectivity' distinguishes it from general status or configuration testing, making the 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 no guidance on when to use this tool versus alternatives like connector_status or connector_test_config. It simply states the action without context about when it is appropriate or when another tool should be preferred. An agent would have to infer usage from the name and description alone, which is insufficient given the number of sibling connector tools.

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

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

The annotation readOnlyHint=true already signals that this is a non-mutating operation. The description adds no further behavioral context, such as whether the test validates syntax, checks connectivity, or performs a dry run. Since the safety profile is covered by annotations, the description is adequate but does not go beyond what is already declared.

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

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

The description is a single sentence with no unnecessary words. It is front-loaded and to the point. However, the brevity results in a lack of substantive detail, which slightly reduces the score from a 5, but as a concise statement it is well-structured.

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

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

For a tool with one parameter and no output schema, the description is too sparse. It does not explain what 'test' entails, what a successful test looks like, whether it returns a status or result, or any prerequisites. An agent would lack enough information to interpret the outcome or know how to handle errors. Given the minimal annotation coverage (only readOnlyHint), the description carries the burden of explaining behavior but fails to do so.

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 fully documents the single parameter 'config' with the description 'Connector config to test.' The tool description adds no additional meaning or constraints beyond the schema. With 100% schema coverage, a baseline of 3 is appropriate; the description does not compensate for any gaps because there are none.

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

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

The description states a clear action ('Test') and a specific resource ('connector configuration'). It is not a tautology and gives a basic sense of what the tool does. However, it does not distinguish it from sibling tools like connector_test or connector_run, which could also involve testing or executing a connector. The name itself hints at the scope, but the description does not explicitly differentiate.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that connector_test might be for testing the full connector, or that connector_discover might be for schema discovery. There are no exclusions or conditions provided, leaving the agent to infer usage solely from the name and 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 annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description need not repeat these. The description adds minimal behavioral context beyond stating that a new object is created; it does not mention failure modes, duplicate behavior, or return characteristics.

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

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

The description is two concise sentences with no redundant words. It immediately states the action and gives a practical pointer to schema_list, making it easy to parse and act on.

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

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

The description is adequate for a create operation: it states the action, scope, and points to schema discovery. There is no output schema, so return-value details are not required, though mentioning the created object's representation could have been slightly more 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 input schema already has 100% description coverage with examples (e.g., parent_fq_name as ['cine-corp', 'car-service']), so the tool description adds no additional parameter meaning. The baseline of 3 is appropriate because the schema carries the semantic load.

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

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

The description uses the specific verb 'Create' and identifies the resource as 'a new object in the current domain,' which clearly conveys the tool's core purpose. It also directs users to schema_list for type definitions, but does not explicitly differentiate itself from sibling CRUD tools beyond the word 'create.'

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 one useful usage hint: 'Use schema_list to see available types and their fields.' However, it lacks explicit guidance on when to use this tool versus crud_update, crud_delete, or crud_get, leaving the decision partially implicit.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, covering the safety profile. The description adds no additional behavioral context beyond the bare fact of deletion—no mention of permanence, cascading effects, or any side effects. While this does not contradict the annotations, it also provides no value beyond what is already structured. Given the annotations exist, the description is minimally acceptable but does not enhance 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 a single, short sentence that front-loads the core action. It is appropriately sized for a generic delete operation—no fluff or unnecessary elaboration. It is concise and well-structured, though its brevity comes at the cost of missing usage and behavioral nuance, which are addressed elsewhere in the evaluation.

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 delete tool with three well-documented parameters and safety annotations, the description is adequate but not fully complete. It lacks explicit mention of return values or confirmation behavior, and it does not clarify the irreversibility beyond the destructiveHint annotation. Since the operation is simple and the schema/annotations cover most context, a score of 3 reflects that it meets the minimum needs but leaves some details to inference.

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

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

The schema description coverage is 100%, meaning every parameter (uuid, tenant, object_type) is already documented in the schema. The description itself mentions no parameters and adds no semantic enrichment beyond the schema. Per the calibration, a baseline of 3 is appropriate when the schema fully describes parameters and the description offers no extra insight.

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

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

The description states a clear verb and resource: 'Delete an object from the current domain.' It is unambiguous about the core action, and the generic CRUD nature is evident from the tool name. However, it does not explicitly differentiate itself from sibling tools like schema_delete, relying on the name prefix 'crud_' to imply object-level deletion. The phrase 'current domain' provides some scope but remains somewhat vague. Overall, it is a clear, albeit generic, purpose statement.

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?

There is no guidance on when to use this tool versus alternatives such as crud_update or schema_delete. The description does not mention conditions, prerequisites, or exclusions. The only implicit hint is the tool name and generic object deletion scope, but the description itself provides no explicit routing or decision support for an agent choosing among similar operations.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to repeat safety. It adds the 'current domain' scoping constraint, which is useful context not captured elsewhere. However, it does not describe error behavior, return format, or any side effects, though the read-only annotation covers the main risk.

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

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

A single sentence with no filler. The essential information (verb, resource, identifier, scope) is front-loaded and every word contributes to the 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 get-by-UUID tool with two parameters and read-only annotations, the description covers the core function and scope. It does not mention the return payload, but the absence of an output schema makes that less critical. Minor gaps like error conditions are acceptable given the tool's simplicity.

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 both parameters (uuid and object_type) already documented in the input schema. The description does not add any parameter-specific semantics beyond what the schema provides, so it stays at the baseline for high 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 states a specific verb ('Get'), a resource ('specific object'), and the identifier mechanism ('by UUID') along with the scope ('from the current domain'). It clearly distinguishes from siblings like crud_search (which would be for searching without a known UUID) and crud_create/update/delete, 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 implies usage when you have a UUID and need a single object, which differentiates it from crud_search. However, it does not explicitly mention alternatives or when not to use it. The phrase 'by UUID' strongly suggests it is not for searching, so the usage context is clear but not formally stated.

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

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

The readOnlyHint annotation already indicates no side effects, and the description's 'Search/list' wording aligns with read-only behavior. It does not add extensive behavioral detail such as permissions or rate limits, but the annotation lowers the bar and 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 concise: three sentences covering purpose, prerequisite guidance, and type examples. It avoids fluff and presents information in a clear, scannable structure.

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 supplies important context about discovering object types and enumerates system types while noting domain variability. There is no output schema, so return-value details are not required, but the description could have explicitly stated that results are a list of matching objects for absolute 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?

All parameters have schema descriptions, so the baseline is met. The tool description does not add additional meaning beyond the schema, aside from reinforcing that object_type can be a system or domain type, which is already partially covered by the parameter description.

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

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

The description clearly states the tool searches/lists objects of any type in the current domain, using the specific verbs 'Search/list' and identifying the resource as objects. It also distinguishes itself from sibling CRUD tools like crud_get by emphasizing search/list over single-object retrieval.

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 useful guidance to call schema_list first to discover object types and clarifies that domain types vary. It does not explicitly contrast with alternatives like crud_get or crud_create, but the search/list framing and prerequisite guidance are clear enough for typical 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 already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, covering the safety profile. The description adds no extra behavioral context such as partial vs full update, permission requirements, or side effects on related records. Since the description contributes nothing beyond annotations, it does not meet the bar for adding value.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the core action immediately and avoids filler or repetition, making it efficient and easy 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?

The description is minimal and does not address key contextual aspects such as whether the update is partial or full, how the 'current domain' is defined, or what happens when the object does not exist. With no output schema and only sparse behavioral annotations, the description leaves an agent without enough context to fully anticipate the operation's outcomes or edge cases.

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

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

Schema description coverage is 100%, so each parameter (data, uuid, tenant, object_type) is already documented in the schema. The description does not add any meaning about how parameters relate or how to construct the data object. Baseline 3 applies because the schema carries the semantic load, and the description adds no supplementary detail.

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

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

The description 'Update an existing object in the current domain' clearly states the verb (update), the resource (existing object), and the scope (current domain). It differentiates from siblings like crud_create, crud_delete, crud_get, and crud_search by the update action. It is not a tautology and adds the 'current domain' context, making the 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 no explicit guidance on when to use this tool versus alternatives such as crud_create or crud_delete. It does not mention preconditions, typical scenarios, or exclusions. The usage context is only implicit from the tool name and sibling list, which is insufficient per the rubric.

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 the operation is a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds no further behavioral context, such as whether linking is additive or replaces existing links, or how errors are handled. It does not go beyond the annotations.

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

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

The description is two concise sentences, front-loaded with the core action. There is no fluff or repetition; every word 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 is adequate for a simple linking action but leaves ambiguity: it does not clarify whether both schema_names and schema_uuids can be provided together, what happens if no schemas are provided (since only project_uuid is required), or what the return value is. Given the lack of an output schema, more context would be helpful.

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 describes all three parameters with clear descriptions, and the description adds little extra beyond mentioning that both schema_names and schema_uuids are accepted. With 100% schema coverage, this is a baseline 3; the description adds no 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 the action ('Link schemas') and the resource ('to a project'), and adds that it accepts schema UUIDs or names. This is specific and distinguishes it from sibling tools like schema_list_project (listing) or schema_delete (deleting).

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. It simply states the action, leaving the agent to infer the use case.

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

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

The readOnlyHint annotation already establishes the non-mutating nature, and the description reinforces that it is a check. However, it does not disclose whether it returns a simple boolean, how policy decisions are made, or what happens on invalid permissions.

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 short sentence with no redundant wording, front-loading the action and object. It is concise and easy 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?

For a single-parameter read-only check the description is adequate, but it omits the return type (expected boolean) and does not clarify how this relates to rbac_get_my_access. The lack of an output schema makes this omission more noticeable.

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

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

Schema coverage is 100% and the parameter description includes useful examples, so the baseline applies. The description adds no additional meaning beyond the schema's own explanation of the permission string.

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?

Description uses a specific verb ('check') with a clear object ('specific permission') and subject ('current user'), making the tool's function immediately clear. It is easily distinguished from sibling rbac_get_my_access by focusing on a single permission check.

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 no guidance on when to choose this tool over alternatives, especially rbac_get_my_access, nor does it describe expected use cases or return behavior. The only clue is the name and generic wording.

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

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

The readOnlyHint annotation already declares the read-only nature, and the description's 'Get' is consistent with that. However, the description adds no additional behavioral context such as return format, error cases, or authentication requirements, though the annotation lowers the bar for safety 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?

The description is a single, clear sentence with no filler or redundancy. It front-loads the action and the resource, making it easy for an agent to understand 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 simple, zero-parameter, read-only tool, the description provides the essential output information: role, permissions, and scope. It could be slightly more complete by describing the output format or potential errors, but the low complexity makes this 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?

The tool has zero parameters, so there is no parameter schema requiring explanation. The baseline for a zero-parameter tool is 4, and the description appropriately omits parameter details.

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

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

The description uses the specific verb 'Get' and identifies the exact resource: the current user's role, permissions, and scope. This clearly distinguishes it from sibling tools like rbac_check_permission, which likely checks a specific permission rather than returning all access information.

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 use when the caller needs their own role, permissions, or scope, but it does not explicitly state when to choose this tool over alternatives such as rbac_check_permission or apikey_get_scope. Usage guidance is only implicit, not direct.

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 indicate destructive and non-read-only behavior. The description adds only a generic caution, without explaining the consequences of deletion (e.g., cascading effects, irreversibility) beyond the force_delete parameter 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 a single, concise sentence that immediately conveys the action and resource, with no unnecessary 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?

The description gives a basic warning but omits critical context such as potential data loss, dependency handling, or any confirmation steps. The force_delete parameter hints at dependencies, but the overall picture is incomplete for a destructive operation.

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?

Both parameters (schema_uuid and force_delete) have descriptions in the schema, providing 100% coverage. The description text itself does not elaborate further, but the schema is sufficiently clear, so the 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 action (delete) and the resource (schema), and it is distinct from other schema-related tools like schema_get, schema_update, and schema_validate.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as schema_update or schema_save. The phrase 'Use with caution' is a general warning, not a specific usage guideline.

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?

readOnlyHint is true and the description consistently describes a read operation with no side effects. It adds useful output context by stating the returned schema definition includes attributes and metadata.

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

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

Two concise sentences with no filler or redundant content. The description is direct and easy 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?

The description states the return value generally, but does not clarify how include_content=false affects the 'complete schema definition' claim, nor does it mention error scenarios. This leaves minor ambiguity for callers.

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?

Both parameters are described with clear meanings and defaults. The phrase 'full details' helps clarify the purpose of include_content, though the description could more directly tie the parameter to varying output.

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 the tool retrieves full details of a specific schema by UUID, using a specific verb and resource. It is easily distinguished from sibling list/delete/update schema 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?

Implies use when needing a single schema's full definition by UUID, but does not explicitly contrast with schema_list or schema_list_project. The guidance is adequate but not explicit about 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?

The readOnlyHint annotation already indicates a read-only operation. The description simply says 'List' and adds no additional context about side effects, permissions, or behavior 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 a single, compact sentence that directly states the purpose without any filler or redundant information.

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

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

Given the simplicity of the operation (no parameters, no output schema), the description is sufficient for an agent to understand what the tool does. It could mention the returned information type, but this is not critical for a basic list operation.

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 is an empty object, meaning all parameters are covered (trivially). There is nothing for the description to add, so a 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 action ('List'), the resource ('schemas'), and the scope ('current domain'), making the tool's 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?

It is clear when to use the tool (to list schemas in the current domain), but it does not mention alternatives or provide explicit when-not-to-use guidance, though the scope is reasonably self-explanatory.

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

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

Annotations declare readOnlyHint=true, so no contradiction. The description adds a small behavioral note via the parameter description about how the project is resolved (defaults to key's project). However, it doesn't disclose side effects or clarify that only linked schemas are returned, which is implied but not explicit.

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

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

A single, front-loaded sentence with zero filler. It directly states the purpose without any extraneous detail.

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 with only two parameters and no output schema. The description is minimally sufficient but lacks details about default behavior for include_content (though schema covers it) and what constitutes 'linked'. No guidance on edge cases like empty results.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description itself adds no additional parameter semantics; the baseline of 3 applies because the schema carries the burden.

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

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

The description clearly states the action (list) and resource (schemas) with a scoping qualifier (linked to the current project). It distinguishes from a generic schema_list by mentioning 'current project', though it doesn't explicitly contrast with 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 guidance on when to use this tool versus alternatives like schema_list or project_link_schemas. The parameter description hints at project-specific usage, but the main description lacks any when-to-use or when-not-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 discloses that schemas are validated before saving and that only successfully saved schemas are returned with their UUIDs. This adds context beyond the annotations (which already mark destructive and idempotent). It clarifies partial success behavior without contradicting 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?

The description is well-structured: purpose statement, critical note, required fields, attribute types, optional parameter, and a comprehensive example. Each section adds necessary information without redundancy, and the most critical usage guidance 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?

With no output schema, the description explains the return value (list of successfully saved schemas with UUIDs). It covers all required input structure, optional parameters, and edge cases like validation. An agent has all information needed to call 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?

While the input schema only lists 'schemas' as an array of objects, the description details the internal structure of each schema object, including required fields, attribute types with concrete examples, and the flat vs. wrapped distinction. This significantly compensates for the schema's vagueness, despite 100% coverage of parameter 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 clearly states the tool's purpose: save/upload schemas to the domain, with validation and a return of successfully saved schemas with UUIDs. It distinguishes itself from sibling tools like schema_delete, schema_get, and schema_update by focusing on creation.

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

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

Provides explicit usage guidance: 'Pass FLAT schema objects directly — do NOT wrap in schema_content', required fields, supported attribute types, and optional project_uuid. It gives clear instructions on how to invoke the tool correctly, even including a full example.

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 simply says 'update', which aligns with the destructiveHint=true annotation, but adds no additional behavioral context such as whether the update replaces the entire schema or just specific fields. No side effects, failure modes, or prerequisites are mentioned beyond what the annotations imply.

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

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

The description is a single, concise sentence with no filler or redundancy. It directly states the action and target, making it highly scannable and appropriately sized for the tool's simplicity.

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

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

The description and parameter details provide enough basic information to attempt a call, but there is no mention of preconditions (e.g., schema must already exist), potential result behavior, or differences from schema_save. This is adequate for a simple update but leaves some contextual gaps.

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

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

All four parameters have individual descriptions that clearly explain their roles (e.g., schema_uuid identifies the target, schema_content provides the full definition). These descriptions are sufficient on their own, and the tool description does not add extra semantic value beyond them.

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

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

The description clearly states the verb 'update' and the resource 'schema definition', making the core purpose unambiguous. The word 'existing' distinguishes it from creation, though it does not explicitly differentiate from schema_save.

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

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

No guidance is provided on when to use this tool versus alternatives like schema_save or schema_delete. The description is purely functional and offers no context for selection.

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

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

The readOnlyHint annotation already marks this as read-only. The description adds value by detailing what validations are performed (conflicts, circular dependencies, reserved names, parent_type correctness), which is beyond the annotation. It does not describe the return format, but for a validation tool this is a minor omission.

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

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

The description is two sentences, front-loaded with the action and followed by specifics. Every word earns its place; there is no fluff or repetition.

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

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

For a validation tool with one parameter, a readOnly annotation, and no output schema, the description covers the essential aspects: what it does, what it checks, and when to use it. The only missing detail is the return value or error behavior, but that is not critical for an agent to decide when to call it. The distinction from build_validate (a sibling) is implicit via the 'schema' prefix and the 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 description coverage is 100% (the single parameter 'schemas' has a description). The tool description does not add further detail about the structure of each schema object, but the parameter name and description ('Array of schema definitions to validate') are self-explanatory. Baseline 3 is appropriate given full 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 states the specific verb 'validate', the resource 'schemas', and enumerates concrete checks (conflicts, circular dependencies, reserved names, parent_type correctness). It clearly distinguishes this from saving or updating schemas, and the name itself is unambiguous.

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

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

The description gives explicit timing guidance: 'Always validate before saving!' This tells an agent when to invoke the tool (before schema_save or schema_update). It does not explicitly name alternatives or exclusions, but the directive is clear and actionable.

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