SpringRoll

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral detail beyond annotations: 'No secrets are included', all sections are returned by default, and each section costs a query. This gives the agent practical expectations for cost and data scope.

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

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

The description is well-structured: a clear opening sentence, a scannable bullet list for sections, and a concise closing tip about narrowing include. Every sentence adds value and the most important behavior is front-loaded.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does so thoroughly for the optional sections. It covers the main output areas and parameter behavior, though the base 'metadata, lifecycle stage, risk score' fields remain somewhat high-level.

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 goes further by explaining what each optional section returns and clarifying the include parameter's default behavior, which the schema alone does not convey. It adds real meaning beyond the parameter names.

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

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

The description states a specific verb and resource: 'Returns an application's registry record' and enumerates what's inside (metadata, lifecycle stage, risk score, optional sections). It clearly differentiates from siblings like app.list by focusing on a single application's record.

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

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

The description gives clear usage context: 'This answers "where is my app up to?"' and advises passing a narrower include when only part of the record is needed to save queries. It doesn't explicitly mention alternatives or when not to use the tool, but the guidance is strong enough to select it correctly.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral context beyond the annotations by specifying 'newest first' and organization scope. It does not enumerate output format or pagination, but the annotations carry the bulk of the transparency burden here.

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, immediately front-loaded with the core action and scope. 'Use search...' is a helpful addition rather than padding. Every word earns its place.

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

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

For a simple read-only list operation, the description covers the core elements: what is being listed, the scope, ordering, and a search assistant. It does not describe the return shape or pagination, which would be useful, but given the read-only annotations and straightforward nature of the tool, the description is sufficient for an agent to call it independently.

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 only 33%, and the description compensates for only one param: 'search' is explained as finding by name or slug. The 'limit' parameter is left entirely to the schema, which only provides numeric constraints, and the 'context' parameter is already documented in the schema. A fuller statement of how limit applies would bring this higher.

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

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

The description uses a specific verb ('Lists') and resource ('applications in this organization'), and adds key distinguishing behavior: newest-first ordering and a built-in search mechanism. This plainly differentiates it from the sibling tools such as springroll.app.get and springroll.app.update.

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: it lists apps org-wide, newest first, and tells the agent to use the 'search' parameter when looking for a single app by name or slug. It does not explicitly discuss when to prefer this over a sibling tool like get, but the guidance is enough for a straightforward listing operation.

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

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

Beyond annotations (which only mark idempotent and non-read-only), the description discloses that the transcript is STORED and READABLE BY ANYONE with access to the application record, that scrubbing of credentials is best-effort, and that retry with the same key and turn indexes overwrites rather than duplicates. This is significant behavioral context for a mutation operation with privacy implications. No contradiction with annotations (idempotentHint matches the overwrite 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?

Three paragraphs each serve a distinct purpose: purpose, privacy/safety, and operational mechanics. No filler sentences; the security caveat and idempotency detail are essential given the tool stores conversation data. Front-loads the action verb in the first sentence.

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, 5-required mutation tool with no output schema, the description is unusually complete: it covers user consent, privacy exposure, credential scrubbing limitations, ordering, and idempotency. The only minor omission is the response format, but that is not necessary for correct invocation. An agent has everything it needs to call safely.

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 covers 6 of 11 parameters (55%). The description adds crucial semantics for `sessionKey` (stable across calls for joining), `turns` (send in order, up to 50 per call), and idempotency (same key + turn indexes overwrites), which are not fully captured by the schema. It does not explain the remaining optional analytics parameters (agentName, modelName, releaseId, tokens), but those are self-explanatory and non-critical.

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: 'Attaches the conversation that produced this application to its record.' It also states the purpose (reference for maintainers and the approving reviewer), which clearly differentiates it from sibling tools like springroll.app.update or springroll.approval.submit. Title and description align on the same action.

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

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

It explicitly commands 'Ask the user before calling this, every time,' establishing a hard precondition. It gives a when-not condition ('If the conversation contained a real secret, do not record it') and operational usage rules: send turns in order, keep sessionKey stable, and expect overwrite on retry. No sibling tool does the same job, so naming alternatives is unnecessary.

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

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

Annotations already signal read-only, idempotent, and non-destructive behavior. The description adds useful context by disclosing what data is returned and that the tool is meant for polling over time, which goes beyond mere annotation coverage.

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 wasted words. The main return behavior is front-loaded, and the polling tip is concise and useful.

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?

Without an output schema, the description gives a meaningful summary of the response contents and use context. It lacks explicit error/not-found behavior details, but the read-only annotations and simple parameter surface keep this from becoming a major omission.

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

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

The schema documents context and provides format-only information for approvalRequestId, while this description gives only an indirect hint that the ID refers to an approval request. It doesn't explain how the ID is obtained or how to pass it correctly, so the parameter guidance is adequate but has a clear gap.

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

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

Description clearly states that the tool returns a specific approval request including reviewers, decisions, and policy snapshot. It differentiates itself from siblings like approval.submit and general app get/list tools by naming the exact resource and its read-only polling role.

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

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

The description gives clear guidance: poll this endpoint to determine whether a release has been approved. It does not explicitly mention when not to use it or name alternative tools, but the intended usage scenario is unmistakable.

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

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

The description adds substantial behavioral context beyond the annotations: it reveals the human-approval requirement, explicitly forbids agent self-approval, states that this is not a deployment action, and documents type-specific defaults and required fields. There is no contradiction with the annotations.

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

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

The description is well-organized with a core workflow constraint up front and a compact bulleted list of type-specific behaviors. Every sentence adds information an agent needs before calling, and there is no redundant restatement of the schema or title.

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 high-complexity tool with 8 request types, nested payloads, and no output schema, the description covers the most critical operational cautions, defaults, and required fields. However, several supported types (e.g., UAT_PROMOTION, OWNERSHIP_TRANSFER, DOMAIN_CHANGE) lack explicit behavioral guidance, and the description does not indicate what the response contains after submission. These are meaningful but not severe gaps.

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

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

Schema coverage is 88%, so the schema already carries most parameter meaning. The description adds value by explaining type-specific semantics: releaseId defaults to the latest release for PRODUCTION_PROMOTION, targetDeploymentId indicates the deployment to restore for ROLLBACK, and justification is required for ROLLBACK and RETIREMENT. It does not detail payload requirements for every request type, but the schema examples help fill that gap.

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

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

The description uses a specific verb ('Submits') and resource ('approval request'), enumerates all supported request types, and clearly differentiates this submit action from the sibling approval.get and deploy.promote tools. It leaves no ambiguity about what the tool accomplishes.

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

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

The description gives explicit usage guardrails: an agent may submit but never decide, user confirmation is required before calling, and it creates review work for named people. It also clarifies that PRODUCTION_PROMOTION does not deploy but merely asks, and directs the agent to call springroll.deploy.promote after approval, which routes away from the wrong sibling.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds a meaningful behavioral constraint: visibility is intentionally not editable in this tool, and the reason is an approval requirement. It does not claim any destructive effects and does not contradict the annotations.

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

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

The description is concise and front-loaded: it names the resource and fields in the first sentence, then gives the single most important exception in the second. Every sentence contributes useful information without redundancy.

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

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

For an 8-parameter mutation tool with low schema coverage and no output schema, the description is somewhat thin. It clearly explains the visibility restriction, which is the most salient domain rule, but it does not clarify whether updates are partial or full replacements, what the response is, or how the less obvious fields like supportContact and department should be valued.

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

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

The description only restates the field names already visible in the schema: description, icon, tags, department, support contact, and data classification. With schema coverage at only 25%, the description needed to add substantive meaning for the other parameters, but it does not explain formats, value semantics, or the update model. The application and context parameters are left to the schema's sparse notes.

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

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

The description clearly states a specific action ('Updates App Portal metadata') and enumerates the exact fields it affects. It also distinguishes itself by explicitly excluding visibility changes, which separates it from the approval-related sibling 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 explicitly states when not to use this tool: visibility changes are deliberately not editable here, and widening an audience requires an approval request. This gives clear routing guidance toward the approval flow while leaving metadata updates to this tool.

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

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

The annotations already establish read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that by explaining that approved fields can be narrower than requested and that a row filter may restrict access, which is non-obvious and valuable for interpreting the result.

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

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

The description is compact and well-structured. The first sentence gives the core result and valid statuses; the second adds important caveats without unnecessary detail. Every sentence contributes meaningful 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 simple read-only status tool with this two required parameters, the description is sufficiently complete. The statuses and response-relevant nuance of narrower fields and row filters are covered, and the absence of an output schema is compensated by the explicit field descriptions.

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 only 50%, and the description does not compensate by explaining the semantic meaning of grantId. The grantId parameter is only invoked as a UUID pattern with no description tying it to the data access request, and the description never clarifies if that ID originates from request_access or somewhere else.

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

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

The description clearly states the action (returns the status) and the resource (a data access request), and enumerates all possible status values. It adds distinctive detail about approved fields and row filters, which helps separate this status tool from siblings like approval.get or request_access.

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 implied: this is for checking the status of a data access request. However, the description does not explicitly say when to use it over sibling tools, nor does it mention any prerequisites or next-step alternatives such as request_access or approval.submit.

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

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

The annotations already indicate a read-only, idempotent, non-destructive operation, and the description adds meaningful behavioral detail: it returns the kind of source system, explains limitations such as lacking support for aggregation, and states that hosts, credentials, table names, and connection strings are never included. It also notes that access requires a data owner's approval, which goes beyond the structured metadata.

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

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

The description is organized with clear conditional paragraphs for the two invocation modes. Every sentence contributes either core behavior, usage guidance, or a security boundary, and the most important information comes first.

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 carries the burden of describing return contents. It specifies list results, product schema details, field sensitivity, glossary information, system kind limitations, and information that will never be exposed. This is enough for an agent to invoke the tool confidently and to decide when to follow up with request_access.

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

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

Both parameters are fully documented in the schema, so the baseline is high. The description adds real value by explaining exactly what happens when `dataProduct` is omitted versus provided, and why the returned information matters before requesting access. This goes beyond the schema's basic variable slUg description and clarifies what the caller should do with the parameter.

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

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

The description clearly names the resource, governed data products, and distinguishes two modes: listing all products when `dataProduct` is omitted, and describing a single product's schema when it is supplied. It also references the access-request flow, so the tool's role is clear relative to its sibling 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 explicitly explains when to omit `dataProduct`, when to supply it, and instructs the agent to read this description before requesting access. It names the alternative action, springroll.connect.request_access, making the decision boundary between describing data and requesting access 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description reveals the approval workflow, possible narrowing by the owner, lack of readable data before approval, and absence of returned credentials. It also clarifies that the gateway enforces the grant on every request, which is non-obvious behavior an agent needs to know.

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 focused sentences front-load the action and scope, then add the approval constraint, access timing, and credential behavior. Every sentence adds information with no filler or repetition.

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

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

For a 6-parameter workflow tool, the description covers the request object, approval process, field narrowing, access timing, and credential handling, complementing a 100%-covered schema. It does not mention how the caller learns the request outcome or that springroll.connect.access_status can be used afterward, which is the only notable 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 documents all six parameters, including field naming and context. The description reinforces the overall intent ('exact fields') and environment scope but does not add meaning beyond the schema, matching the baseline of 3.

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

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

The description opens with a specific verb and resource ('Requests access to a data product') and adds the scope 'for one environment' and 'naming the exact fields the application needs.' This clearly identifies the operation and distinguishes it from status or approval sibling tools without requiring schema inspection.

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: call this when an application needs a data product's fields, expect an approval step, and know that nothing is readable until approval. It does not explicitly name alternatives like springroll.connect.access_status or when not to call it, so it stops short of a full 5.

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

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

Annotations already declare the tool read-only, idempotent, open-world, and non-destructive, so the description does not need to restate that. It adds useful behavioral credite by noting it returns identity/permission context and, notably, 'It never returns credentials,' which is important safety context for an agent.

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

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

The description is only two sentences and front-loads the return content first. Every clause adds value: what is returned, when to call it, why it matters, and the important credentials caveat. There is no repetition of annotation data.

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

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

Even with no output schema, the description states the meaningful groups of returned information: organization, identity, permissions, and deployment runtimes. It might have provided slightly more detail about output shape or field names, but for a simple read-only introspection tool the description gives an agent sufficient context for correct use.

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% for the single 'context' parameter; the schema explains its exact purpose and length and viewpoint constraints. The description adds no parameter detail, but that is acceptable because the schema already carries the full parameter documentation.

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

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

The description names a specific operation and resource: it 'Returns the organization, identity, and permissions this agent token acts as, together with the deployment runtimes configured for it.' This is clearly separating context retrieval from app, deployment, and approval tools, although it does not explicitly name which sibling it is being contrasted with.

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 strong sequencing guidance with 'Call this first' and explains the situational value: 'it tells you which tenant you are in, what you are allowed to do, and whether a deployment can actually land.' It does not explicitly say when not to use it or mention alternative tools such as springroll.policy.check, but the intended context is clear.

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

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

Annotations already signal a non-read-only, idempotent operation, and the description adds substantial behavioral context: it registers new projects, redeploys existing ones, falls back from git to uploaded files, drops build artifacts, refuses .env and .git paths, imposes upload limits, and reports offending paths. This goes well beyond the structured fields and gives an agent accurate expectations for side effects and constraints.

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 dense and front-loaded: the first sentence states what the tool does and what it returns, followed by tightly organized source-selection bullets and constraint callouts. Every paragraph earns its place given the complexity of the tool, and the formatting makes scanning easy.

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 24-parameter deployment tool with no output schema, the description covers the return behavior, source options, environment routing, approval semantics, upload limits, and failure-prone bundling pitfalls. Nothing essential to calling the tool correctly is missing.

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

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

Schema description coverage is only 46%, so the description carries real parameter-semantic weight. It clarifies the archive format and exact tar command, explains when repositoryUrl is appropriate and that it has no size limit, and adds nuance to ref and fallback behavior. Not every optional parameter is discussed, but the schema already documents those 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?

The description names a specific action on a specific resource: registering/attaching source/deploying a project through SpringRoll's Deployment workflow. It also distinguishes itself from sibling tools by explaining the Direct-to-Production vs Staged routing and by deferring polling and promotion elsewhere.

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 decision rules for when to pass repositoryUrl vs archive, what happens when both or neither are supplied, and why source rather than build output should be uploaded. It even tells the agent which cases should use a different tool path, such as Staged applications requiring explicit promotion and approvals.

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

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

The description goes well beyond the annotations by disclosing a meaningful behavioral invariant: the already-built artifact is reused, so tested bytes are shipped. It also transparently states that promotion requiring approval will be refused until approval exists. Annotations indicate mutation (readOnlyHint=false) and idempotency, and the description's behavior is consistent; there is no contradiction.

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

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

Two short paragraphs contain only value-adding content: the core behavior, the artifact-reuse guarantee, and the approval-gating caveat. There is no filler or repetition of title or schema fields.

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 output schema, this is complete enough. It covers what happens, notes the approval requirement, advises the correct order for production flows, and leverages the idempotency key behavior already present in the schema. The sibling names further contextualize where it fits.

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 semantics beyond the schema by explaining that deploymentId should refer to a tested deployment and that targetEnvironmentType must be the 'next' environment in the chain. The idempotencyKey purpose is already well 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 clearly states the specific verb 'promote' with the resource 'deployment' and the precise scope: moving a tested deployment through the environment chain development -> uat -> production. It stands apart from siblings like springroll.deploy.status by describing the actual promotion action and its artifact-reuse behavior.

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

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

The description gives clear context: use this when a deployment has been tested and should advance environments. It also provides a key precondition for approval-gated environments ('For production, submit the request first') and notes that refused approval will block promotion. It stops short of naming the exact sibling tool, springroll.approval.submit, so alternatives are 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?

The description adds meaningful behavioral detail beyond the readOnlyHint and idempotentHint annotations by explaining that the status is refreshed from the runtime provider while the build is in progress. It also discloses the full set of statuses and the log-inclusion behavior, which helps the agent understand what to expect and when to act.

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

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

The description is compact and front-loaded, with the core behavior and status list in the first sentence. Every clause earns its place: refresh behavior, status enumeration, polling guidance, and log usage instructions. There is no redundant or filler language.

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 status tool with no output schema, the description covers the key return concept, the status vocabulary, the log behavior, and the polling context. It is slightly incomplete in that it does not mention how to obtain the deploymentId, what poll interval to use, or the shape of the log lines, but these are minor given the otherwise rich annotations and 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 75%, so most parameters already carry documentation. The description adds useful semantics for includeLogs by calling the logs 'normalised' and advising use after failure, but it does not clarify how to obtain or format deploymentId, which lacks a schema description beyond its UUID pattern.

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

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

The description clearly states the tool 'Returns a deployment's current status' with a specific verb and resource, and goes beyond the title by detailing the refresh behavior and enumerating the possible statuses. This distinguishes it from sibling tools like springroll.deploy.promote and springroll.deploy, which are about action rather than observation.

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

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

The description gives explicit usage context: 'Poll this after deploying rather than assuming success' and advises passing includeLogs when the status is FAILED. It does not explicitly name alternative tools or provide when-not-to-use guidance, but the usage direction is clear and actionable.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive; the description goes further by explaining that it shares implementation with springroll.deploy, that credentials never affect ranking, and that returned alternatives include readiness plus unlock actions. It also discloses that ranking is computed from the public catalog alone and that the receipt matches what a deploy would decide right now. No contradiction with annotations exists.

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

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

Three dense paragraphs front-load the core purpose in the first sentence and then add credential independence, deploy equivalence, and usage guidance. There is slight redundancy between 'before any provider account is connected' and the earlier 'without deploying,' but every other 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?

No output schema exists, so the description must convey the return value; it enumerates the receipt contents: provider and plan, monthly cost range, plan limits, what was inferred, and why each other candidate lost. It also explains readiness and unlock actions per ranked alternative, making the tool's behavior before account connection fully understandable.

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 carries the parameter documentation; the description contributes no parameter-level specifics beyond reinforcing that placement hints are provider-neutral and that omitted fields are inferred. This is a solid baseline-3 case where 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?

Opens with a specific action and resource: 'Scores where SpringRoll would place this application and what it would cost.' It immediately contrasts with deploy ('without deploying or writing anything') and names the deploy sibling, so an agent can distinguish preview from actual deployment. The title and description align.

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

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

States explicit use cases: 'Use it to put the cost and the limits in front of the user before deploying, or to ask what-if questions by varying the placement hints.' It also explains that it works before any provider account is connected, which is a useful precondition. It does not spell out that actual deployment should go to springroll.deploy, but the 'without deploying' contrast makes that boundary clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by stating 'without creating anything,' explaining that application mode provides 'specific remediation for each failing rule,' and pointing to an example resource—behavioral context beyond the annotations.

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

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

The description is well organized and front-loaded with the core purpose. Each paragraph covers one mode with a clear trigger, and the closing 'Send exactly one of the two' eliminates ambiguity. There is no filler or redundant restatement of the title.

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

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

Given the tool's two-mode complexity and lack of an output schema, the description covers the essential decision-making context: when to call, what to send, how to avoid blocked deployments, and where to find the manifest shape. A small gap is that it does not describe the report structure, but the schema already documents parameters and defaults.

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 extra semantic value by grouping manifest/application as mutually exclusive modes, clarifying when releaseId is relevant (with application), and referencing the springroll://manifest/example resource for document shape, which is not in the schema.

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

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

The description opens with a specific verb and resource: 'Reports which governance policies an application would pass or fail for an environment.' It also clearly separates the two invocation modes (manifest validation vs. application explanation), making its purpose unambiguous and distinguishable from siblings like springroll.deploy or springroll.deploy.promote.

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

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

The description gives explicit when-to-use guidance for both modes: use manifest before springroll.deploy to avoid rejected submissions, and use application when a deployment is rejected with POLICY_BLOCKED. It also states 'Send exactly one of the two,' preventing ambiguous calls.

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