coderegistry

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

With no annotations provided, the description carries the full behavioral burden and handles it well. It discloses the return value (API credentials), the failure mode if required fields are missing, cold-start timeout behavior with retry advice, and that no API key is required. This is substantial behavioral context beyond the basic create action.

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

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

The description is concise and front-loaded: purpose and return value first, then required parameters, then failure and operational behavior. Every sentence provides actionable information, and there is no filler or 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 lack of annotations and output schema, the description covers all essential invocation details: purpose, required inputs, failure condition, returned credentials, auth requirement, and timeout handling. Optional parameters are already fully documented in the schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds role clarifications for email, name, and team_name, but does not add meaning beyond the schema for the optional integrator fields. This meets the baseline for high schema coverage.

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

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

The description states a specific verb and resource: 'Creates a new Code Registry account and returns API credentials.' This clearly differentiates it from sibling tools like create_project or create-code-vault by naming the exact resource type. It goes beyond the tool name and adds the result of the call.

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 for when to use the tool: when creating a new Code Registry account. It also lists the required fields and warns that all three must be provided or the call will fail, which helps the agent decide to use this tool. It does not explicitly name alternatives or exclusions, but the resource-specific language makes the usage context unambiguous.

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

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

With no annotations, the description carries the full burden and handles it well: it discloses that analysis is queued, cold starts may time out and require retries with backoff, X-API-Key is required, the response contains next_steps.commands that must be executed, and source code never leaves the machine for LOCAL_AGENT. These are meaningful behavioral details beyond the schema.

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

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

It is long because the tool is complex, but every sentence earns its place: mode selection, Docker fallback, autonomous upload, retry behavior, auth requirements, and next-step commands. The numbered source_type list and front-loaded purpose sentence make it scannable despite the length.

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

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

For a 10-parameter tool with no output schema and no annotations, the description is nearly complete: it covers mode selection, credentials, network behavior, source data handling, and required post-call commands. It falls short on explaining the valid 'AGENT' source_type and does not describe the overall response shape beyond next_steps.commands, so it is not a full 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real value by explaining how to choose source_type based on Docker availability, how to prepare FILE_ARCHIVE inputs, uploading autonomously, and using api_key when headers are unsupported. It loses a point because the valid enum value 'AGENT' is never described in either the description or the schema.

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

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

The description opens with a specific verb and resource: 'Creates a code vault and queues the initial analysis.' It immediately distinguishes this from siblings like reanalyze-code-vault, delete-code-vault, and get-code-vault-results by making clear this is the creation/initial-analysis step.

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 environment-based routing: LOCAL_AGENT when Docker is available, FILE_ARCHIVE when Docker is not available, and GIT only when the user supplies a reachable repo URL. It also says to act autonomously when uploading archives. However, the schema also lists 'AGENT' as a valid source_type and the description gives no guidance for it, which is a small but real routing gap.

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

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

With no annotations, the description carries the behavioral disclosure burden. It usefully discloses the auth requirement and the api_key fallback, but it does not state what is returned after creation, whether creation can fail, or any additional side effects beyond the implicit 'creates'.

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-loads the core purpose, and contains no redundant or filler language. Every sentence contributes either the action or the critical auth prerequisite.

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 reasonably complete for a simple creation tool with a fully documented schema, but it relies on the schema to clarify user_id provenance and omits the expected response/return value and potential failure conditions. Given the absence of an output schema and annotations, a short statement of return behavior would make it 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?

Schema description coverage is 100%, so the schema already documents all four parameters. The description mostly restates the api_key fallback that is already in the schema's api_key description, adding the small context about generating keys in the web app, but no substantial new parameter meaning.

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

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

The description opens with a specific verb and resource, 'Creates a project for a team user,' which clearly identifies the operation and its target. This is unambiguously distinguishable from sibling tools such as create_account, delete_project, and list_projects because the resource and action are explicit.

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 invocation context: it states the authentication prerequisite (X-API-Key), explains where keys come from, and offers a fallback when headers are unsupported. It does not name alternative tools or provide exclusion criteria, 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?

With no annotations, the description carries the full behavioral burden and does so well: it discloses the destructive scope (account, projects, vaults), the required X-API-Key authentication, and the api_key parameter fallback. This is exactly the kind of side-effect and auth context an agent needs.

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

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

Three short sentences, each carrying distinct information: scope, authentication, and parameter fallback. The destructive scope is front-loaded, so an agent immediately grasps the consequence before considering invocation.

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

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

For a destructive mutation tool with no output schema and no annotations, the description covers all critical invocation concerns: what is deleted, how to authenticate, and how to pass the key when headers are unavailable. The confirm requirement is available in the schema, so nothing needed for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining when to use the optional api_key parameter (when headers aren't supported), which goes beyond the schema's 'Optional API key' text. The confirm parameter is already fully documented in the schema.

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

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

The description opens with the specific verb 'Deletes' and names the exact resource: 'team account plus all projects and vaults.' This clearly distinguishes it from sibling tools like delete_project and delete-code-vault by emphasizing the broad destructive scope.

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

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

The description provides clear operational context by stating the authentication requirement and the fallback for clients that cannot set headers. It doesn't explicitly name sibling alternatives or state when not to use it, but the scope language ('plus all projects and vaults') makes the tool's role evident.

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

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

With no annotations provided, the description carries the full burden. It discloses the destructive action, including the cascade of 'related analysis data,' and the authentication requirement. However, it does not mention irreversibility, confirmation behavior, or what happens to associated resources beyond 'related analysis 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?

Two sentences with no filler. The primary action is front-loaded, followed immediately by the essential authentication constraint and parameter fallback. 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 two-parameter destructive tool with no annotations and no output schema, the description covers purpose, side effects, and auth fallback. It lacks an explicit irreversibility warning, but the core information an agent needs to invoke the tool correctly is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minor value by clarifying the api_key fallback for clients that cannot set headers, but it does not meaningfully expand on vault_id beyond what the schema already states.

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

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

The description starts with a specific verb and resource: 'Deletes a code vault and related analysis data.' This clearly distinguishes the tool from sibling delete_project and delete_account operations, and the target resource 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 provides clear authentication context: X-API-Key is required, with an explicit fallback to passing api_key in arguments when headers are not supported. It does not explicitly name alternatives or exclusions, but the delete vault usage is strongly implied by the verb and resource.

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

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

With no annotations, the description discloses the destructive scope (project plus vaults) and the authentication requirement, both of which go beyond the raw schema. It does not mention irreversibility or response behavior, but for a simple delete operation the key side effects are communicated.

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

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

Two sentences with no filler; the action is front-loaded and the auth guidance is relevant and compact. 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 tool with one required parameter, it covers what is deleted, the required API key, and the header fallback path. It omits irreversibility and return-value details, but nothing required to construct a valid call is missing.

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

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

Schema description coverage is 100%, so the parameters are already fully documented. The description adds no substantial parameter meaning beyond what the schema says about api_key and project_id.

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

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

The description opens with 'Deletes a project and its vaults', which is a specific verb and resource and clearly identifies the cascade scope. This distinguishes it from delete_account and delete-code-vault, so an agent can immediately select the right deletion tool.

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

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

It provides a clear prerequisite (X-API-Key) and an explicit fallback for clients that cannot set headers, which is practical invocation guidance. It does not explicitly name alternative tools for deleting only a vault, but the cascade statement implies the boundary between this and delete-code-vault.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds the X-API-Key requirement and the api_key fallback, which are useful. However, it does not mention error behavior, response shape, or side effects; 'Returns' implies read-only but is 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?

Two sentences with no filler: purpose comes first, followed by the prerequisite and the fallback. Every clause carries actionable information.

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

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

For a zero-required-param read operation, the description plus schema is largely sufficient: it covers what is returned, how to authenticate, and the api_key fallback. It lacks response detail and error cases, but the low complexity keeps this from being a major gap.

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

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

Schema coverage is 100% and the single api_key parameter is already documented with description and example. The description restates the same header-fallback behavior without adding new semantic meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Returns the team owner account information.' This unambiguously distinguishes it from sibling create/delete/rotate account tools and other get_* tools focused on projects, vaults, or code analysis.

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 authentication context and the header-vs-argument fallback, but it never explicitly says when to use this tool versus alternatives. The intended use is implied by the tool name and 'Returns', yet there is no 'when not to use' or explicit sibling differentiation.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses cache-only behavior, no fresh analysis triggering, the 404 case for code_score, paid plan access requirements, and the X-API-Key or api_key authentication path.

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

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

The description is front-loaded with the core return behavior, then covers exclusions, caching, id constraints, access requirements, and auth fallback. Each sentence contributes distinct value with no filler.

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

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

The description covers the important invocation context: routing, caching, auth, access level, and parameter constraints. Since there is no output schema, a slightly more explicit description of the response shape would make it fully complete, but the listed analysis categories provide a reasonable high-level picture.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics, particularly that analysis_key=code_score is invalid here and that exactly one of project_id or vault_id must be supplied, but most parameter meaning already exists in the schema.

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

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

The description states a specific operation: it returns Code IQ automated analyses for either a project or a single vault. It also explicitly excludes The Code Score and names get-the-code-score as the correct sibling, making differentiation clear.

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

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

It gives direct routing guidance: use get-the-code-score for Code Score and do not pass analysis_key=code_score here. It also clarifies that results are cached only, so fresh analysis is never triggered, and documents exact id requirements and auth prerequisites.

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

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

With no annotations provided, the description carries the full burden and meaningfully explains access restrictions: 'Requires full data access (a paid plan; verification-only plans are not included)' and 'Requires X-API-Key', plus the api_key fallback for header-less clients. It does not discuss rate limits or response limitations beyond the schema, but the get-style operation is represented clearly.

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

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

Four short sentences with no filler. The purpose is front-loaded, followed by the required ID constraint, then access requirements and the header fallback. Every sentence contributes.

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

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

The description covers the selection constraint and access requirements well, and 'code smell findings' is adequate for a list-fetch tool even with no output schema. It could say more about the returned finding structure, but the schema already documents filters and pagination parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely repeats what the schema already states: exactly one of project_id or vault_id, and the fallback use of api_key when headers are not supported. It adds little new meaning beyond the structured schema.

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

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

The description clearly identifies the resource ('code smell findings') and scope ('project (all vaults) or a single vault'), with a specific verb ('Returns'). It does not explicitly contrast a sibling tool like get-code-vault-results, so differentiation is implicit rather than stated.

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

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

It gives an explicit invocation rule: 'Provide exactly one of project_id or vault_id.' It also states the required permission level and API key prerequisite, giving clear context for when the tool can be used, though it does not name alternative 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?

With no annotations provided, the description carries the full disclosure burden and delivers: version-based completion semantics, exponential backoff retry policy, the destructive-ish behavior that reanalysis removes access to prior versions, and the X-API-Key/auth requirement with an api_key fallback. These are exactly the behavioral traits an agent needs beyond the basic 'returns URLs' claim.

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

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

Four sentences, each earning its place: purpose, completion rules, retry policy, and versioning/auth constraints. The most important identifying information is front-loaded, and the dense operational details follow in a logical order with zero 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?

Despite having no output schema and no annotations, the description is operationally complete: it defines the return artifacts (snapshot/comparison URLs, null comparison for 1.0.0), the readiness signal, the polling cadence, the versioning limitation, and the authentication path. Nothing an agent needs to invoke this endpoint correctly is left to guesswork.

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% — both api_key and vault_id are documented in the schema. The description reinforces the api_key fallback ('If headers aren't supported, pass api_key in arguments') but adds no new per-parameter meaning beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description opens with 'Returns report URLs (snapshot/comparison) for a vault' — a specific verb, resource, and scope that clearly differentiates it from siblings like get-code-vault-results and get-code-vault-summary. The word 'URLs' pins down exactly what artifact this tool produces.

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

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

Gives clear operational context: completion rules tell the agent when to expect ready data versus a null comparison, and the backoff schedule dictates how to poll when not ready. It notes the latest-version-only limitation ('prior versions are no longer accessible here') but does not explicitly name an alternative tool for retrieving prior versions, so it falls 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly documents async behavior, tier differences, polling timing, latest-version-only semantics, authentication requirements, and the delayed availability of AI insights. This goes well beyond a minimal description.

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

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

The description is long but every sentence earns its place: polling behavior, tier differences, timing expectations, status semantics, authentication, and API key fallback are all actionable. It is front-loaded with the core purpose and then layers crucial operational details without redundancy.

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

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

Given the complexity of async analysis, no output schema, and no annotations, the description is remarkably complete. It tells the agent how to poll, what to expect for free vs paid tiers, how to handle missing AI insights, what happens when reanalysis starts, and how to authenticate. No critical calling 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?

Schema coverage is 100%, so the parameters are already documented. The description adds meaningful context by clarifying that api_key is a fallback for clients that cannot set X-API-Key headers, and it ties vault_id to create-code-vault or list_vaults, which helps the agent source valid values.

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: 'Returns analysis results for a vault.' While it clearly identifies the tool's function, it does not explicitly contrast itself with sibling tools like get-code-vault-summary or get-code-vault-reports, so some ambiguity about exactly which result type this returns remains.

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 strong usage context: it explains that analysis is async, gives an explicit polling schedule with exponential backoff, and tells the agent what to do when status is 'processing' or when ai_insights is empty. It does not name alternative tools or state when not to use this tool, but the guidance is clear enough for correct invocation.

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

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

With no annotations provided, the description carries the full disclosure burden and does so well: it reveals async analysis, the exact polling cadence, time estimates, the latest-version-only behavior, and the API-key requirement. This is genuinely useful behavioral context beyond what the schema or annotations would supply.

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 seven sentences long but each sentence carries operational value: purpose, polling, timing, latest-version semantics, and auth. It is somewhat wordy in the timing section, but it is front-loaded with the primary purpose and contains no fluff.

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

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

For a simple two-parameter read tool with no output schema, it adequately covers authentication, header-vs-argument fallback, vault_id provenance via the schema, polling behavior, and version semantics. It does not enumerate possible response status values, but that is a minor gap for invocation.

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

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

The schema already documents both parameters fully (100% coverage), including the api_key fallback and the source of vault_id. The description restates the header-vs-argument fallback but adds no substantively new parameter meaning, so the schema-carries-the-load 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?

States a specific verb and object ('Returns the latest version/status info for a vault') and sharpens the scope by noting this endpoint only serves the latest version and prior versions become inaccessible after reanalysis. This differentiates it from siblings like get-code-vault-results or get_vault without requiring their schemas.

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

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

Provides concrete invocation guidance: poll with exponential backoff when status is 'processing', sets expected latency expectations, and explains the authentication fallback for clients that cannot send headers. It does not explicitly name alternative tools or say when-not-to-use this tool, 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?

With no annotations provided, the description carries the full behavioral burden. It discloses plan requirements, API-key requirements, the X-API-Key header fallback via api_key argument, and the aggregation semantics ('all vaults' vs 'single vault'). It does not explicitly state that this is a read-only operation or describe the response format, but the behavioral disclosures are substantial.

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

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

The description is four sentences, front-loads the core purpose, and every sentence earns its place: scope, id exclusivity, plan/access requirement, and authentication fallback. It is detailed but not bloated, and it does not repeat the full parameter schema.

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

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

For a 10-parameter tool with no annotations and no output schema, the description covers the most critical operational context: id selection, plan gating, authentication, and aggregation behavior. The only notable gap is that it does not describe the response shape or documented return fields, but the description's explicit focus on detected components and filters leaves the agent well-equipped 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%, so the schema already documents all 10 parameters in detail. The description adds no new parameter-level semantics beyond reinforcing the existing oneOf constraint and the api_key header fallback. Baseline 3 is appropriate because the schema carries the parameter documentation 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 opens with a specific verb and resource: 'Returns detected open-source/CMS components for a project (all vaults) or a single vault.' It clearly distinguishes this tool from sibling get-* tools by naming the resource type and the two scoping modes (project vs vault), so an agent knows what it does and how it differs.

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 on when to call the tool: when component data is needed at project or vault level. It also provides usage constraints — 'Provide exactly one of project_id or vault_id' — and access prerequisites such as paid plan and API key. It does not explicitly name alternatives or exclusions, so it falls just 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?

With no annotations, the description carries the full burden. It adds valuable auth/plan requirements and the header-fallback behavior. However, it doesn't describe error behavior, pagination semantics, or the full response structure beyond listing a few stat names, leaving some behavioral transparency gaps.

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

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

Three sentences with no filler. The first sentence front-loads the purpose and scope, the second states the key constraint, and the third covers auth. 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 stats endpoint, the description covers purpose, scope, authentication, and output content. It doesn't mention error cases or response format in detail, but the output fields are named and the schema descriptions cover all parameters, so the tool is callable without missing critical context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the 'exactly one' constraint and the api_key fallback, both already encoded in the schema. It adds no meaningful parameter detail beyond what the schema already provides.

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

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

States a specific verb and resource: 'Returns aggregated contributor stats (commit count, lines added/deleted, first/last commit)'. Clearly identifies scope ('for a project (all vaults) or a single vault'), which differentiates it from sibling tools like get-git-history or get-components.

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 clear context: exactly one of project_id or vault_id, full data access required, X-API-Key required, and an api_key fallback for clients without header support. It doesn't explicitly name alternative tools or when-not-to-use conditions, but the context is sufficient for correct routing.

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

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

With no annotations, the description carries the behavioral burden and is largely successful: it discloses authentication requirements, plan-level eligibility, the api_key fallback, and the project/vault scoping. It does not describe response shape or ordering, but the operation is clearly a read and no hidden effects are implied.

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 front-loaded sentences: the first states purpose and scope, the second covers plan eligibility, and the third covers auth fallback. Every sentence earns its place with no filler or repeated tool name.

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?

Together with the detailed schema, the description covers selection, filters, pagination, plan requirements, and authentication. The main gap is the absence of an explicit return format or ordering, and there is no output schema to compensate. This is a moderate gap for a history read, but the tool is still callable correctly with the provided information.

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 9 parameters are already covered with descriptions in the schema, so the baseline is 3. The tool description mostly restates the oneOf constraint and the api_key fallback, both of which are already present in the schema. It adds little semantic meaning beyond what an agent can already read from the parameter definitions.

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

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

The description opens with a concrete action and resource: 'Returns git commit history for a project (all vaults) or a single vault.' It explicitly distinguishes the two scopes, avoiding tautology and separating this from sibling tools focused on reports, scans, or vault metadata.

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

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

It states when the tool applies and gives a clear selection rule: provide exactly one of project_id or vault_id. It also provides when-not guidance by excluding verification-only plans and requiring full data access, plus an auth fallback for header-less clients. No sibling tool competes for this commit-history use case, so alternative routing is not needed.

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

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

With no annotations, the description carries the behavioral disclosure burden. It explicitly discloses the X-API-Key requirement and provides a fallback mechanism via api_key, and 'Returns' conveys a read-only operation. It could add more about error behavior, but the essential side-effect and auth profile are covered.

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

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

Two tight sentences with no filler. The core behavior is front-loaded, and the auth note 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 get-by-id tool, the description and schema together provide everything needed: the target id, the auth method, and the fallback path. No output schema exists, but the description's 'Returns a specific project' adequately indicates the result.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description reinforces the api_key fallback but adds little beyond the schema's existing explanation. 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 clear verb and resource: 'Returns a specific project by id.' This distinguishes it from sibling tools like list_projects, create_project, and delete_project. The scope is unambiguous for an agent deciding whether to call 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 clearly signals this is for fetching one project by its id, which implies when to use it over list_projects. It does not explicitly name alternatives or exclusion cases, so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses deduplication, scope behavior (all vaults vs one vault), plan requirements, and API-key handling. It stops short of describing potential errors, rate limits, or return structure, but it provides substantial behavioral context beyond the schema.

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

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

The description is compact and front-loaded: purpose first, then the critical selection rule, then the necessary auth context. Every sentence earns its place and there is no redundant restating of the tool name or schema.

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

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

For a read-only security findings tool with 11 parameters and no annotations or output schema, the description covers the essential selection and auth concerns clearly. It could mention pagination limits or error behavior, but the schema already documents limit/offset and the description covers the core invocation requirements.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by condensing the oneOf constraint into clear guidance and by explaining project_id/vault_id consequences. It also clarifies the api_key param's role as a header fallback, which the schema only hints at.

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 ('Returns') and a specific resource ('security findings') with an explicit scope: aggregated across all vaults in a project or limited to a single vault. It also uses 'deduplicated' to add precision and distinguish the result set. This makes the tool's purpose unambiguous even among many sibling get-* 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 invocation context: provide exactly one of project_id or vault_id, and explains the difference between the two scopes. It also states authentication requirements and the api_key fallback. It does not explicitly name alternatives or exclusion conditions, but the usage context 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?

With no annotations, the description carries the full burden of behavioral disclosure and does so well. It states the paid-plan/data-access requirement, explains that missing access or an ungenerated score returns empty sections rather than an error, and clarifies the X-API-Key versus api_key argument authentication path.

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

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

Three dense, purposeful sentences front-load the result and scope, then cover plan requirements, edge-case behavior, and authentication. No repetition 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?

Everything needed to call the tool correctly is present: parameter exclusivity, auth requirements, plan prerequisite, and the empty-response behavior. The description only vaguely references 'sections/priorities' without an output schema, so it falls just short of fully specifying the response shape.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the exactly-one constraint and the api_key fallback, but those are already present in the schema; it adds no new parameter-level 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 identifies the resource as 'The Code Score' with its dimensions and 1000-point scale, and specifies the two scopes: aggregated project or single vault. It does not explicitly contrast itself with sibling code-vault tools, so it stops short of a 5.

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

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

Usage is implied: call this when you need Code Score data for a project or vault, and the schema's oneOf constraint makes the exactly-one-id requirement explicit. However, there is no explicit guidance on when not to use it or which sibling alternative to choose instead.

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

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

With no annotations, the description carries the behavioral burden. It discloses the auth requirement and the api_key fallback for clients without header support, and 'Returns' signals a read-only retrieval. It does not discuss error behavior or response shape, but for a simple get-by-id operation those are not critical gaps.

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 compact sentences with the core action first and the authentication fallback second. Every clause earns its place, and the parenthetical about generating a key is useful rather than 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 two-parameter, single-object retrieval with no output schema, the description gives an agent everything it needs to make the call: target ID, auth key, and header fallback. It does not enumerate vault fields or error cases, but that is 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 coverage is 100%, so the baseline is 3. The description adds useful meaning for api_key by clarifying that an API key is required and can be generated in the web app, while also explaining when to pass it as an argument. vault_id is already sufficiently described in the schema.

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

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

States a direct retrieval verb ('Returns'), names the resource ('specific vault'), and qualifies it by id, so it is clearly distinct from list_vaults and from get-code-vault-* aggregate tools. No ambiguity about what operation this performs.

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 usage context is implicit: this is the right tool when one vault is needed by ID. It provides helpful authentication guidance, but it never explicitly says when not to use this tool or names alternatives like list_vaults for collection queries.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the authentication requirement, where to generate an API key, and the header-vs-argument fallback. It does not mention pagination, ordering, or explicit side-effect absence, but 'Lists' implies a read-only operation and the auth guidance covers the main behavioral concern.

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

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

Two sentences with no filler. The main purpose is front-loaded, and the authentication detail earns its place as it directly affects invocation.

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

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

For a simple list operation with one optional parameter and no output schema, the description covers the operation, scope, and authentication path. It omits response format and pagination details, but those are reasonably inferable from the tool name and purpose.

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 api_key at 100% coverage with examples and a clear description. The description only restates the header/argument fallback, which is consistent but adds no significant new parameter semantics, 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 specific verb ('Lists'), a resource ('projects'), and a scope ('for the authenticated team'). The phrase 'all projects' clearly distinguishes it from siblings like get_project (single project) and create_project/delete_project.

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 clear usage context: authentication via X-API-Key, how to obtain a key, and a fallback to passing api_key in arguments when headers are unsupported. It does not explicitly name sibling alternatives, but the context is clear and no exclusions are needed.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the auth mechanism and the fallback for header-less clients, which is useful. However, it does not state whether the operation is read-only, what the response contains, or whether pagination is involved. Listing is implicitly safe, but the description leaves these behavioral traits unstated.

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

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

The description is two sentences with no filler. The core function is front-loaded, and the authentication note is concise and actionable. Every clause earns its place.

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

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

The tool has no output schema, so the description should compensate by explaining return values or list behavior. It does not mention what a vault listing looks like, ordering, or pagination. Authentication and parameters are well covered, but the missing response semantics leave a notable gap for an agent that must consume the 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 baseline is 3. The description adds meaningful value beyond the schema by explaining why api_key may be needed ('If headers aren't supported') and by clarifying the X-API-Key requirement. This helps an agent decide whether to populate the optional parameter.

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

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

The description states a specific verb and resource: 'Lists vaults within a project.' It clearly defines the scope (within a project) and implies the operation returns multiple items. It does not explicitly distinguish from sibling tools like get_vault or list_projects, but the plural 'lists' and project-scoping make the purpose reasonably unambiguous.

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

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

The description provides clear usage context by specifying the authentication requirement ('Requires X-API-Key') and instructing when to use the api_key argument instead of headers. However, it does not state when to choose this tool over alternatives such as get_vault, nor does it mention any exclusions or prerequisites beyond authentication.

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

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

With no annotations, the description carries the burden and discloses important side effects: it creates a new analysis version that replaces access to prior version data, and it behaves differently depending on source type. It also states auth requirements. It does not fully describe queued-job status or failure semantics, leaving some behavioral uncertainty.

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 earns its place: definition, mode-specific behavior, the latest-version caveat, and auth fallback. The most important purpose 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?

The description covers target resource, side effects, source-type behavior, and auth, which is strong for a tool with no output schema. It is slightly incomplete because it doesn't describe the response/status surface for queued GIT/FILE_ARCHIVE reanalysis, outside of the local-agent commands.

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 explains all five parameters. The description's api_key note roughly mirrors the schema's own explanation and adds no new param 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 first sentence names a specific action ('creates a new analysis version') with a specific resource ('existing code vault') and a constraint ('using its existing source settings'). This clearly distinguishes reanalysis from create-code-vault and from read-only vault tools.

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

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

It establishes when to use the tool: you have an existing vault and want a new analysis version without changing source settings. It also gives mode-specific follow-up instructions (local agent must run again vs queued automatically) and warns that standard read tools show only the latest version. It does not explicitly name sibling alternatives, but 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?

With no annotations, the description carries the full burden. It discloses the authentication requirement and parameter fallback, but does not explicitly state that the old key is invalidated or describe other side effects of rotation. The word 'fresh' hints at replacement, yet the destructive aspect is left implicit.

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 primary function is stated first, followed by authentication requirements and a parameter fallback. Every sentence earns its place.

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

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

For a simple tool with three optional parameters, the description covers purpose, authentication, and the key parameter usage. It does not describe the response format or invalidation behavior, but given the tool's simplicity and no output schema, this is nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining when the api_key parameter should be used (for clients that cannot set headers), which is meaningful semantic 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 action ('Issues a fresh integrator API key') with a clear resource. It is immediately distinguishable from all sibling tools, none of which involve API key rotation.

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 context: it requires X-API-Key authentication and explains the fallback of passing api_key as an argument when headers are unsupported. It does not explicitly contrast with alternatives, but no sibling tool offers the same functionality.

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