coderegistry

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

Without annotations, the description carries the full behavioral burden and discloses key traits: it returns API credentials, all three required fields must be provided or the call fails, cold starts can cause the first request to time out with a retry recommendation, and no API key is required. It does not cover rate limits or whether account creation is reversible, which prevents a 5.

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

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

The description is four sentences, each earning its place: it states the action, lists required fields with explanations, warns about cold-start retries, and clarifies that no API key is needed. It is front-loaded with the most critical information.

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

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

Given this is a creation tool with no annotations and no output schema, the description provides sufficient context: required fields, behavior of the return (API credentials), a retry strategy for cold starts, and authentication requirements. It could mention the existence of optional parameters, but overall it is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by specifying the roles of the three required parameters (account owner's email, full name, and team/company name) and emphasizes that all three must be provided or the call will fail. It does not mention the two optional parameters, but the schema already covers 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 opens with a specific verb and resource: 'Creates a new Code Registry account and returns API credentials.' This distinguishes it from siblings like get_account, delete_account, and rotate_api_key, which all operate on the same resource but with different actions.

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

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

The description clearly implies when to use this tool: to create a new account. It does not name alternatives, but the action is self-contained and does not compete with sibling tools for the same purpose. There is no explicit 'when-not-to-use' guidance, keeping this from 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 and does: it discloses the privacy property (source never leaves the machine for LOCAL_AGENT), the mandatory post-call action (next_steps.commands MUST be executed), the auth requirement (X-API-Key, with api_key fallback for clients that can't set headers), and the cold-start timeout/backoff 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?

Well front-loaded: the core action and response contract come first, then a numbered enumeration of source types. It is long, and the source_type guidance largely restates the schema's own description, which is the only real redundancy. Otherwise every sentence carries operational weight.

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 a oneOf schema and no output schema, the description still covers what an agent needs: source selection, credential handling, the required follow-up command execution, auth, and the transient-failure retry path. Nothing material 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 already 100%, so the baseline would be 3. The description adds genuine conditional semantics on top: which parameters matter for each source_type (source_url required for FILE_ARCHIVE/GIT, ignored for LOCAL_AGENT) and what credentials are needed for private GIT repos.

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

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

Opens with a specific verb+resource (creates a code vault) plus a second effect (queues the initial analysis), which no sibling tool claims. It is immediately distinguishable from create_account, create_project, and reanalyze-code-vault.

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 an explicit decision procedure for source_type: LOCAL_AGENT when Docker is available (preferred), FILE_ARCHIVE when it is not, GIT only when the user supplies a reachable repo URL. It also names prerequisites per branch and instructs the agent to act autonomously rather than deferring to the user.

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 usefully discloses the authentication model (X-API-Key header or api_key argument fallback). It says nothing about what happens on duplicate names, permission requirements for the team, failure modes, or what the response contains.

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 action and the auth requirement, no filler. Slightly terse on the creation semantics, but nothing is wasted.

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 mutation tool with no annotations and no output schema, the auth detail is the key addition, but an agent still lacks return-value expectations (does it yield a project id?) and error/duplicate behavior. Adequate but not complete.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description's only parameter-relevant content, the api_key fallback, duplicates the schema's own description. Baseline 3 is correct; no meaning is added beyond the schema.

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

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

States a specific verb and resource: 'Creates a project for a team user.' The scope ('for a team user') narrows it beyond the bare name. It does not explicitly distinguish itself from create_account or create-code-vault, but the 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?

Gives one conditional usage rule (pass api_key when headers aren't supported), which is genuinely actionable. However, it offers no guidance on when to use this tool versus create-code-vault/other creation siblings, and no prerequisites or exclusions beyond the auth note.

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 meaningful work: it discloses the destructive blast radius (all projects and vaults) and the auth requirement (X-API-Key, with a fallback). It omits whether the action is reversible or how the confirm flag interacts with execution, which is the main residual gap for a destructive tool.

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

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

Three tight sentences with the destructive purpose front-loaded before the authentication detail. Every sentence carries information about what the tool does or how to authenticate.

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, no-output, no-annotation tool, the definition covers the critical facts: cascade scope and authentication. It would be fully complete if it stated irreversibility or that confirm must be true to proceed, but the schema enum already enforces the latter.

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 api_key and confirm are already documented in the schema, including the header fallback and the confirm-to-proceed semantics. The description largely restates the api_key rationale, 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?

States a specific verb and resource ('Deletes the team account') and immediately qualifies scope with the cascade ('plus all projects and vaults'). This scope wording distinguishes it from siblings like delete_project and delete-code-vault, which act on single resources.

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

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

Usage is implied by the account-wide cascade, and it usefully explains the header-vs-argument auth path. However, it never states when to prefer this over the narrower delete_project / delete-code-vault siblings or any preconditions 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?

No annotations are provided, so the description carries the burden. It discloses the auth mechanism (X-API-Key or api_key argument) and the cascade behavior ('related analysis data'), which is valuable. However, it omits that deletion is destructive and irreversible, a critical trait for a delete operation with no annotations to signal 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?

Three sentences, front-loaded with the core action and resource. No wasted words. Auth details follow logically. Could be slightly tighter but 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 delete tool with no annotations and no output schema, the description should warn about irreversibility, cascade scope, and any auth errors. It covers auth path but leaves the destructive nature unstated, which is the most important thing an agent needs to know before invoking a delete.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds the auth fallback behavior (api_key in arguments when headers aren't supported), which is useful context beyond the schema's terse field description. Baseline 3 is appropriate since the schema does most of the work.

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+resource ('Deletes a code vault') and clarifies the scope includes related analysis data. It distinguishes from get/summary siblings clearly. It does not explicitly differentiate from delete_account or delete_project, but the resource is specific enough to stand apart.

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 when-to-use guidance or caution about irreversibility. The description does not mention alternatives like get_vault or that deletion is permanent, nor does it note prerequisites beyond auth. An agent knows what it does but not when or whether to prefer another 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?

With no annotations, the description carries the full burden and does disclose two meaningful traits: the destructive cascade to vaults and the authentication requirement/fallback. It omits irreversibility, required permission level, and failure behavior on partially-populated projects, which matter for a delete operation.

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

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

Two short sentences, front-loaded with the destructive action and scope, followed by auth mechanics with no filler. The parenthetical about generating a key in the web app is marginally verbose but still useful to an agent that lacks credentials.

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

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

For an unannotated destructive tool with no output schema, the description covers the essential blast radius and auth needs but leaves irreversibility, permission requirements, and error/edge behavior unspecified. Adequate to call correctly, thin on 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 100% and both parameters are documented there, so the baseline is 3. The description's mention of api_key as a header fallback restates the schema description rather than adding format or precedence details beyond it.

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

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

States a specific verb and resource ('Deletes a project') and adds the cascade scope ('and its vaults'), which immediately separates it from delete-code-vault and delete_account. It stops short of explicitly naming an alternative or confirming whether nested vault data is fully purged, so it is clear but not sibling-aware.

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 a conditional usage instruction for the api_key argument when headers cannot be set, plus where to obtain a key, which is genuinely actionable context. It gives no guidance on when deletion is appropriate versus archiving or when-not-to-use, so usage remains implied rather than explicit.

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 present, the description carries the full behavioral burden and does well on the most important dimension: it states the authentication requirement (X-API-Key) and an alternative path (api_key argument) for clients that cannot set headers. It stops short of describing permissions, failure modes, or response shape, which keeps it out of the top score.

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

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

Three short sentences, front-loaded with the purpose before the auth mechanics. Every sentence contributes something, though the header-generation note is slightly parenthetical.

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 ideally sketch what 'account information' contains or note the shape of the response. It covers the input/auth side completely but leaves the return value vague for a tool that an agent must interpret.

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 api_key parameter is fully documented in the schema, including its purpose as a header fallback. The description's mention of api_key largely repeats the schema rather than adding new syntax or constraint detail, so the baseline 3 applies.

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

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

The description names a specific verb and resource: it 'returns the team owner account information', which is more precise than a bare 'get account'. It does not explicitly differentiate itself from siblings such as get_project or list_projects, but the account-scoped noun makes the distinction reasonably 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?

The description implies when to call it (retrieving account info) and gives practical invocation guidance about headers vs. the api_key argument. It offers no explicit when-not condition and never points to an alternative sibling, so usage is only implied.

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: it discloses that only cached results are returned and a fresh analysis is never triggered, the 404 behavior for code_score, the X-API-Key auth requirement, and the api_key-in-arguments fallback. These are exactly the behavioral traits an agent needs before invoking.

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?

Despite covering many constraints, it is front-loaded with the core purpose and then tightens with routing, caching, and auth in a scannable sequence. Every sentence carries an actionable constraint, so nothing is wasted.

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 analytical tool with no output schema, it adequately describes what the returns contain (trimmed per-analysis results, aggregated or vault-scoped) and fully covers auth, exclusivity, and caching. Nothing an agent needs to call it correctly appears to be 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, but the description adds meaning beyond the schema: the mutual exclusivity of project_id/vault_id, the semantics of aggregation vs single vault, and the analysis_key restriction to non-code_score values. It stops short of enumerating valid analysis_key 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?

States a specific verb (Returns) and resource (trimmed Code IQ automated analyses covering architecture, scalability, EOL, AI functionality) with explicit scope (project-aggregated or single vault). It explicitly distinguishes itself from the sibling get-the-code-score by naming the excluded 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?

Gives explicit routing: use get-the-code-score for The Code Score, and do not pass analysis_key=code_score here. It states the exactly-one-of project_id/vault_id constraint and the plan/access prerequisites (full data access, paid plan, verification-only excluded), leaving little to inference.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses the plan gate (paid, verification-only excluded) and the auth path (X-API-Key, with an api_key argument fallback for header-less clients). It does not cover pagination behavior or rate limits, hence not a 5.

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

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

Four short sentences, each front-loaded with its own concern: scope, scope-selection rule, plan gate, auth. No filler and no 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?

No output schema exists, but the description covers auth, plan entitlement, and the scope duality that an agent needs before calling. Return shape and pagination semantics are left to the schema fields, which is a minor gap for a findings-listing tool.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description only restates the mutual-exclusion constraint already encoded in the schema's oneOf, adding no new syntax or format 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?

States a specific verb+resource ('Returns code smell findings') and distinguishes the two scopes it serves: aggregated across all vaults in a project vs. a single vault. An agent immediately knows what this retrieves and at what granularity.

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

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

Gives explicit selection rules for project_id vs vault_id ('exactly one of', with the scope each yields) and preconditions (full data access / paid plan, verification-only plans excluded). No mention of adjacent sibling tools such as get-security-issues or get-code-vault-results, so it stops short of full routing 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 burden and does so thoroughly. It discloses auth requirements (X-API-Key, api_key fallback), completion semantics tied to version, a retry/backoff strategy, and a versioning limitation that could cause unexpected results if missed. This is unusually rich operational context for a read-style tool.

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

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

The description is front-loaded with the core return value, then layers on completion rules, retry guidance, versioning caveat, and auth details. Every sentence earns its place, but the dense run-on flow could be slightly better structured for scanning.

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 and involves async completion, versioning, and auth, so the description needs to carry a lot. It covers those areas well, but omits the shape of the returned URLs (beyond naming snapshot/comparison) and does not explicitly state that the operation is read-only, leaving a small 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 description coverage is 100%, so the schema already fully documents both parameters, including the origin of vault_id and the purpose of api_key. The description repeats the api_key fallback already present in the schema and adds no new meaning beyond what the structured field provides, 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 (Returns) and resource (report URLs for a vault), with the added detail of snapshot/comparison types. It does not explicitly name or differentiate from sibling tools like get-code-vault-results or get-code-vault-summary, 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?

It gives clear context for when to call: after vault creation or reanalysis, with explicit completion rules and a retry schedule. It also notes that the endpoint always returns the latest version only and prior versions become inaccessible after reanalysis. However, it does not name alternative tools or state when not to use this one, so it is a strong 4 rather than 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 and does so richly: async semantics, exponential backoff cadence (5s→60s), expected runtimes, that only the latest version is retrievable once reanalysis starts, X-API-Key requirement, and AI-insight timing. This is exactly the behavioral context an agent needs beyond structured fields.

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

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

Front-loaded with purpose and tier behavior, then flows into polling, timing, authentication. It is long, but nearly every sentence carries actionable operational detail, so waste is minimal despite the density.

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 annotations and no output schema, the description must carry the full load; it covers tiers, async status, facets, AI-insight status values, and auth. It stops short of describing the actual returned structure, but the operational coverage is strong.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description repeats the api_key fallback and the vault_id provenance rather than adding new syntax; baseline 3 applies 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?

States a specific verb and resource ('Returns analysis results for a vault') and clarifies the tier-dependent scope of what is returned. It never names the closely related siblings (get-code-vault-summary, get-code-vault-reports), so an agent must infer which result-bearing tool to pick.

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 operational context (async, poll when status is 'processing', poll again for AI insights), which tells the agent how to use it. However, it never states when to choose this tool over the sibling summary/reports/score tools, leaving tool selection to inference.

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

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

With no annotations, the description fully discloses the async lifecycle, the backoff schedule, realistic wait times (20–30 min under 500k LOC), the irreversible loss of prior versions after reanalysis, and the auth requirement including the api_key header workaround. That is unusually complete behavioral context for a read endpoint.

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?

Purpose is front-loaded in the first sentence, followed by the polling procedure, timing expectations, version caveat, and auth note in a logical order. It is on the longer side but essentially every sentence 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 2-param tool with no output schema, the description covers status semantics ('processing'), polling behavior, latency, version retention, and auth. It stops short of enumerating the returned fields, but the agent has enough to call and interpret 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 both parameters (vault_id, api_key) are already documented in the schema, including the api_key fallback rationale. The description restates the auth fallback but adds no new syntax or format detail beyond what the schema provides, 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?

States a specific verb and resource ('Returns the latest version/status info for a vault') and clarifies its scope ('always returns the latest version only'), which distinguishes it from the report/results siblings. It does not explicitly name or differentiate itself from get_vault, 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?

Gives clear operational context: poll only when status is 'processing', using exponential backoff (5s–60s), and sets expectations for analysis duration. It lacks explicit when-to-use-this-vs-<sibling> routing (e.g., versus get-code-vault-results or get_vault), so it is clear context without exclusions.

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

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

With no annotations, the description carries the full burden and does well: it discloses the auth mechanism (X-API-Key, with an api_key argument fallback when headers are unsupported) and an access-tier constraint (paid plan required; verification-only plans excluded). It does not state pagination behavior or the default/limit caps, but those live in 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?

Front-loaded with the core purpose, then the selection constraint, then prerequisites and auth in descending priority. Every sentence carries information, though the auth/header sentence is slightly tangential to the primary call decision.

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 read tool with no annotations and no output schema, the description covers the essentials an agent needs: what is returned, the mutually exclusive id params, access tier, and auth. It stops short of describing the return shape or sort/pagination defaults, but the schema documents those.

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 already 100%, so baseline is 3, but the description adds real meaning: it explains that project_id aggregates across all vaults while vault_id scopes to one, and it clarifies the api_key fallback beyond the schema's terse field text. The exactly-one-of constraint is duplicated from the oneOf schema and required-fields block, keeping it short of a 5.

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

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

Specific verb ('Returns') plus resource ('detected open-source/CMS components') and explicit scope ('a project (all vaults) or a single vault'). This clearly distinguishes it from siblings like get-security-issues, get-code-smells, and get-contributors without needing to open the schema.

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

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

The description gives a hard selection rule ('Provide exactly one of project_id or vault_id') and a prerequisite (full data access / paid plan), but never names an alternative tool or explains when an agent should choose this over the other component-adjacent tools. Usage is implied rather than guided.

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 delivers important behavioral context: it requires full data access (paid plan, verification-only excluded) and requires X-API-Key with an argument fallback. It doesn't cover pagination semantics or rate limits, but the auth/plan prerequisites are the material behavioral facts.

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

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

Front-loaded with purpose, then the parameter rule, then auth requirements — each sentence carries load. The auth sentence is slightly verbose (three clauses) but nothing is wasted.

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 9-parameter tool with no annotations and no output schema, the description covers the returned fields, the exclusivity constraint, and the auth/plan prerequisites. It is essentially complete, though pagination behavior and the missing-output-schema return shape rely entirely on the schema.

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

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

Schema description coverage is 100%, so all nine parameters are already documented. The description restates the project/vault exclusivity rule (also encoded in the oneOf) but adds no syntax or semantic detail beyond the schema, 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?

States a specific verb+resource and enumerates the returned aggregates (commit count, lines added/deleted, first/last commit). It clearly distinguishes the two aggregation scopes (project = all vaults vs single vault), letting an agent tell it apart from siblings like get-git-history without opening a schema.

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

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

Explicitly states the operating condition 'Provide exactly one of project_id or vault_id' and what each selects, plus the plan prerequisite. It gives clear context for use but never names a sibling alternative (e.g. get-git-history) or a when-not-to-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?

With no annotations, the description carries the full burden and does well on access control: it discloses the paid-plan requirement, excludes verification-only plans, and explains both auth paths (X-API-Key header or api_key argument fallback). It stops short of describing read-only semantics, return shape, or rate limits.

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

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

Four tight sentences, zero filler, front-loaded with purpose and scope before the exclusivity rule and auth details. Every sentence conveys a constraint the caller needs.

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

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

Covers the key risk areas for a 9-param, no-annotation, no-output-schema tool: resource scope, mutual exclusivity, and authentication/plan gating. The one remaining gap is that nothing describes the shape of returned commit records, which the absent output schema cannot compensate for.

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 every parameter and the oneOf mutual-exclusivity constraint. The description restates the 'exactly one' rule and adds rationale for api_key, but contributes little beyond the structured data. 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 ('Returns git commit history') and explicitly distinguishes the two scopes: project-wide (aggregated across all vaults) vs. single vault. No sibling tool in the list covers git history, so the agent can identify this tool immediately.

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 the selection rule: 'Provide exactly one of project_id or vault_id,' with each parameter's semantic scope documented. It does not name alternative tools for adjacent needs, but for a uniquely-scoped resource tool the routing guidance 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, and it does disclose a real behavioral trait: the X-API-Key requirement and the api_key argument fallback for header-less clients. However, it says nothing about read-only semantics, permission scoping, or what happens when the project id does not exist.

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 compact sentences with the core purpose front-loaded; nothing is padded. It could be tighter by folding the parenthetical API-key generation note, but it stays readable.

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

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

For a simple get-by-id with a fully documented schema and no output schema, the auth coverage is the main gap-filler. It stops short of explaining not-found behavior or returned fields, which leaves a mild hole an agent might 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?

Schema description coverage is 100%, so the schema already documents both project_id and the api_key fallback, and the description largely restates the api_key note. Baseline 3 applies; no additional syntax or format detail is added.

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

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

States a specific verb and resource ('Returns a specific project by id'), so the agent knows this is a single-item lookup. It does not explicitly contrast with the sibling list_projects, but the 'by id' phrasing implicitly distinguishes retrieval-by-key from enumeration.

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 authentication instructions but no guidance on when to use this tool versus list_projects or the other get_* siblings. There are no stated prerequisites, exclusions, or error conditions that would help an agent choose.

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 load well: it discloses deduplication, aggregation scope, a paid-plan access gate, and the X-API-Key requirement with an api_key fallback for header-less clients. It omits rate limits and return/pagination behavior, but covers the traits an agent most needs before calling.

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 tight sentences, each doing distinct work (scope, exclusivity, plan gate, auth). The scope statement is front-loaded and nothing is repeated from the schema verbatim beyond the exclusivity rule it must reinforce.

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

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

For an 11-parameter read tool with no output schema and no annotations, the description covers scope, access gating, and authentication well. It would be stronger if it described the return shape (finding fields) or pagination semantics, but the schema handles limit/offset.

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, but the description adds real meaning: it explains the project_id/vault_id mutual exclusion as an invocation rule and clarifies when to fall back to api_key in arguments. Filter parameters (tag, severity, status) are left to the schema, which documents them adequately.

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 deduplicated security findings') plus the two scoping modes (project/all vaults vs. single vault). An agent can distinguish it from siblings like get-code-smells or get-code-vault-results from the description alone.

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

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

Gives explicit invocation conditions: 'Provide exactly one of project_id or vault_id', plus the plan prerequisite (full data access required; verification-only plans excluded) and auth options. It does not compare itself to sibling reporting tools, so it stops short of the top tier.

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 does so well: it discloses the paid-plan/access requirement, the auth mechanism (X-API-Key) with an api_key argument fallback, and the notable non-error behavior of returning empty sections/priorities when access is missing or data is not generated. These are exactly the traits the agent cannot infer from structured fields.

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 paragraph is front-loaded with the core purpose, then layers constraints, auth, and edge-case behavior in descending priority. Every sentence carries actionable information with no filler.

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

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

For a read tool with no output schema, the description covers purpose, parameter exclusivity, access prerequisites, auth, and the empty-response fallback. An agent has everything needed to call it correctly and interpret a non-error empty 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 vault_id, project_id, and api_key semantics. The description's 'exactly one of' rule and api_key fallback note restate what the schema and its oneOf constraint already express, adding little beyond the structured data. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Returns The Code Score') and precisely scopes it to two modes: aggregated across a project or a single vault. This distinguishes it from siblings like get-code-vault-summary, get-code-vault-results, and get_project without the agent needing to open those schemas.

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

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

It gives a clear selection rule ('Provide exactly one of project_id or vault_id') that tells the agent how to choose between the two aggregation modes. It does not, however, explain when to prefer this tool over related siblings such as get-code-smells or get-security-issues for the same data.

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 it does contribute real value by disclosing the auth mechanism and the header-less fallback. It says nothing about failure modes (invalid id, missing key), permissions, or what the returned vault contains, so the behavioral picture is only half-drawn.

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, the primary purpose front-loaded, and the auth caveat placed last where it belongs. No filler, though the parenthetical about generating keys in the web app is slightly tangential to 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 two-parameter read with 100% schema coverage, the description covers purpose and auth adequately. With no output schema, it could have sketched what a vault record contains, but nothing critical to making the 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 both parameters are already documented in the schema, and the description's note about api_key for header-less clients merely echoes the schema's own wording. Baseline 3 is appropriate 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?

States a specific verb and resource ('Returns a specific vault by id'), which cleanly separates it from the plural list_vaults and the more specialized get-code-vault-* siblings. It stops short of explicitly naming those alternatives, but the singular-scoped retrieval 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?

There is no statement of when to use this tool versus list_vaults or the code-vault retrieval siblings; the agent must infer selection from the name alone. The sentences present are about authentication, not 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?

No annotations are provided, so the description carries the full burden. It does disclose a genuine behavioral trait beyond the schema: the X-API-Key requirement, how to obtain a key, and the header-less fallback. However, it says nothing about pagination, result ordering, or scoping limits on what "all" means, which matters for a full-burden 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?

Three short sentences, front-loaded with what the tool returns before the auth requirement. Minor redundancy with the schema's api_key description, but nothing wasted overall.

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

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

For a zero-required-arg list tool with no output schema or annotations, the description covers the main obstacle an agent would hit (authentication) and identifies the target scope. Only pagination/return-shape details are absent, which is a small gap at this complexity.

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

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

Schema coverage is 100% and the single parameter is already fully documented, including the fallback purpose. The description's mention of passing api_key in arguments largely restates the schema, 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?

States a specific verb and resource ("Lists all projects") and scopes it to "the authenticated team", which is enough to distinguish it from get_project and the vault tools. It stops short of naming a sibling it is not, so it does not reach the top band.

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 by the verb (enumerate projects), and the auth prerequisite is spelled out, but there is no when-to-use-this-vs-get_project guidance or any exclusions. Minimum viable for a read-only listing tool.

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

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

No annotations are provided, so the description carries the burden. It usefully discloses auth behavior (X-API-Key required, obtainable in the web app, and the fallback of passing api_key as an argument), but says nothing about pagination, result limits, ordering, or that the operation is a read-only listing.

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

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

Three short sentences with no filler, and the core purpose is front-loaded before the auth instructions. Slightly compressed, but nothing is wasted.

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, the description covers purpose, auth requirement, and the header-less fallback, which is what an agent needs to invoke it. Only pagination/return-shape detail is absent, a minor gap for a listing call.

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

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

Schema description coverage is 100% and both parameters are documented there, so the schema already does the work. The description restates the api_key fallback but adds no format or constraint detail beyond the schema's example and 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 gives a specific verb and resource with scope ('Lists vaults within a project'), which lets an agent distinguish it from get_vault (single vault) and list_projects (different resource). It stops short of explicitly naming those siblings as 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?

It states the authentication prerequisite and how to satisfy it, which is real usage context, but gives no guidance on when to choose this over get_vault or list_projects, nor any filtering/pagination 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?

With no annotations, the description carries the full burden and delivers: it discloses the LOCAL_AGENT re-run requirement and next_steps.commands, the automatic queuing for GIT/FILE_ARCHIVE, the destructive/wrapping behavior that prior version data becomes inaccessible, and the auth requirements including the api_key fallback.

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

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

Front-loaded with the core action, then behavioral notes and auth. It is somewhat dense but every sentence carries non-redundant information; 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?

No output schema exists, yet the description describes the relevant return behavior (next_steps.commands for LOCAL_AGENT) and the side effect on downstream summary/results/report tools. This is complete enough for an agent to invoke and anticipate 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 all five parameters. The description adds auth-related context (X-API-Key header vs api_key argument) but supplies no additional semantics for vault_id, author, or comment beyond the schema.

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

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

States a specific verb and resource: 'Creates a new analysis version for an existing code vault.' It clearly distinguishes itself from create-code-vault (new vault) by operating on an existing vault using existing source settings.

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

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

Explains the context of use (reanalyzing an existing vault) and what happens per source type (LOCAL_AGENT vs GIT/FILE_ARCHIVE). It does not explicitly name the sibling to use for creating a new vault, but the 'existing vault' framing implies the distinction.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose a genuine trait absent from the schema: external auth via X-API-Key is required. But for a rotation operation it never states whether the previous key is revoked, whether the change is reversible, or what the caller receives back.

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 with the core action front-loaded and no filler. The final sentence about api_key duplicates the schema's own description, costing a bit of redundant length in an otherwise tight definition.

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 and no annotations, so the description must cover both safety and results. It covers authentication adequately but omits what the response contains (presumably the new key) and the fate of the old key, which is the single most important detail for a rotate tool.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, establishing a baseline of 3. The description's line about passing api_key in arguments only restates what the api_key schema description already says, and integrator_id/integrator_name are not addressed at all.

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 ('Issues a fresh integrator API key') with enough precision that an agent knows exactly what the operation produces. No sibling tool competes for this action, so differentiation is trivially satisfied.

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 supplies a prerequisite ('Requires X-API-Key') and a fallback path for header-less clients, which is useful invocation context. However, it never says when this tool should be invoked versus other setup/account operations, nor anything about when rotation is warranted or discouraged.

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