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?

The description adds meaningful behavior beyond the annotations: requests are 'limited and deduplicated,' and artwork 'never blocks deployment or publishes itself.' It does not cover failure modes or asynchronous completion, but given the annotations already establish idempotency and non-destructiveness, this is strong additional context.

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

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

Three terse sentences front-load the core action, then add constraint and safety context; every sentence earns its place. There is no redundant restatement of the title or schema.

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

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

For a 4-required-parameter tool with no output schema, the description explains purpose, limitation, deduplication, and non-blocking behavior, which is enough to invoke correctly. It does not mention the response/result or how to retrieve the queued draft, leaving a small gap an agent may need to infer from sibling tools.

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

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

Schema descriptions cover context and idempotencyKey thoroughly, while application and purpose are bare in the schema. The description only indirectly maps to parameters via 'app's reviewed purpose' and 'deduplicated,' adding marginal meaning without value constraints, examples, or format details.

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

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

The description opens with a specific verb and object, 'Queue one premium icon draft,' and anchors it to 'the app's reviewed purpose.' This makes the operation distinct from sibling save/upload/deploy tools by emphasizing 'draft' and explicitly stating that it never publishes itself.

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 wording implies when it should be used: when a non-blocking, premium icon draft is needed from an app's reviewed purpose. 'Artwork never blocks deployment or publishes itself' hints that this tool is not the final save/upload/deploy step, but no alternative tools are named and no explicit when-not-to-use conditions are stated.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds meaningful context: the resource is a private draft and the call does not publish or expose the app. This goes beyond the annotation hints, though it does not cover authentication or return 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?

Two short sentences with no filler. The action and resource are front-loaded, and the second sentence adds a useful non-goal clarification without redundancy.

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

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

For a simple read-only tool with strong annotations, the description is mostly sufficient: it identifies what is read and what side effects are avoided. The lack of an output schema is partially offset by the simplicity, but a brief mention of what is returned would make it fully complete.

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

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

The schema covers the 'context' parameter well but leaves 'application' completely undocumented. The tool description does not clarify what 'application' should contain (ID, slug, name, etc.), and with 50% schema coverage this is a significant gap for an agent trying to construct a valid call.

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 ('Read') and resource ('private app listing draft and available artwork'). It also explicitly states what the tool does not do ('Does not publish or expose the app'), which helps distinguish it from publishing, saving, and uploading siblings.

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

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

The intended use case is implied by 'Read a private app listing draft' — it should be used when you need the draft rather than the published app. However, the description names no alternative tools or explicit when-not-to-use conditions, leaving some routing responsibility to the agent.

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 contradiction with annotations: 'Save' aligns with readOnlyHint=false, and draft-saving matches destructiveHint=false and idempotentHint=true. Adds value beyond annotations by disclosing 'private draft' visibility, the revision-read precondition, and the owner/admin publishing boundary. Doesn't state what happens to an existing draft (overwrite vs append), but idempotency is already flagged in annotations.

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

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

Four sentences, each earning its place: core purpose first, then prerequisite, content-quality guideline, and permission boundary. No fluff, no repetition of schema or annotation data. Ideal front-loading for an agent scanning quickly.

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

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

Covers purpose, precondition, content quality, and permission. But with no output schema, the return behavior is unstated, and the `application` parameter meaning is absent. The nested draft structure is reasonably left to schema. For a 4-required-param tool without an output schema, some return-value guidance would round it out.

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 25% (context is the sole described param). The description maps 'listing copy' to the draft object's name/tagline/description fields, 'image IDs' to iconAssetId and screenshots[].assetId, and references the revision param. But the `application` parameter is left unexplained in both schema and description, and draft field details are deferred to 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+resource: 'Save listing copy and selected image IDs to a private draft.' The 'private draft' phrase clearly differentiates from presentation.upload and presentation.get siblings. However, it doesn't explicitly name or contrast those siblings, 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?

Provides execution context: 'Read the revision first' establishes a prerequisite, and 'Use factual copy and real, reviewed screenshots' sets content-quality expectations. But it offers no explicit when-to-use vs alternative guidance (e.g., when to pick this over presentation.upload), so the routing burden is left to the agent.

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, the description discloses that metadata is stripped, that images remain private until selected in an owner-published snapshot, and that confidential content should never be uploaded. This adds meaningful behavioral context without contradicting the annotations.

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

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

The description is tight and front-loaded, with each sentence adding a distinct piece of information: what to upload, format/size constraints, metadata handling, privacy behavior, and a warning. There is 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?

It covers the most important input semantics and privacy expectations, but it omits what the 'application' parameter should contain and gives no indication of the response or follow-up result. Given there is no output schema, these gaps leave the agent with some uncertainty.

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 prose gives useful meaning for base64 (allowed formats, size limit) and kind (screenshot vs icon), which the schema only partially conveys. However, the required 'application' parameter is left unexplained, and the low schema coverage means the description does not fully compensate for all parameters.

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

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

The description states a specific action — uploading a real screenshot or app icon — with explicit formats and size limits. It clearly distinguishes this tool from the sibling generate_icon by emphasizing that the upload must be a real image.

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 clearly indicates this is the path for uploading actual screenshots or icons, and it sets a firm exclusion by warning against confidential content. However, it does not explicitly name alternatives such as generate_icon or state exact conditions for choosing between them.

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?

Goes well beyond the annotations: 'An agent may submit but never decide', a human approver is required, an agent cannot approve its own request, and it creates review work for named people. It also clarifies that PRODUCTION_PROMOTION does not deploy, which is exactly the kind of side-effect transparency that prevents misuse of a mutation 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?

Front-loads the core constraint (submit but never decide) and the confirm-with-user warning, then organizes type-specific behavior into scannable bullets. Length is justified by eight request types and eight parameters; every sentence carries actionable content.

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 and a nested payload object, the description covers the missing pieces: what the call produces (review work, not a deployment), the human-approval gate, and the follow-up call to springroll.deploy.promote. Nothing an agent needs to call it correctly is absent.

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?

Despite 88% schema coverage, the description adds conditional, cross-parameter semantics the schema cannot express: defaults for releaseId and targetEnvironmentType, which types require justification, that UAT_PROMOTION requires targetEnvironmentType, and that the ROLLBACK deployment goes in payload.targetDeploymentId defaulting to the last successful one.

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 ('Submits an approval request') and enumerates all eight supported request types, so the agent knows exactly what it creates. It is clearly distinguishable from siblings like springroll.approval.get and 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?

Explicitly states when to use it versus the alternative ('this does NOT deploy... Once approved, call springroll.deploy.promote'), and gives a hard usage constraint plus a prerequisite ('Confirm with the user before calling this'). Decision rules are spelled out per request type rather than left 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?

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?

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 indicate a mutating, idempotent operation, but the description goes much further: it explains that build output is not accepted, that .env and .git are refused, that upload limits exist, that duplicate bundles are content-addressed, and that production safety checks still apply even when approvals are skipped. This is rich behavioral context well beyond the 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 description is long, but the tool is complex and every sentence adds critical information: source selection, exclusions, limits, environment safety, and workflow routing. It is front-loaded with the core process and return behavior, then uses bullets to keep the decision logic scannable.

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

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

Given 24 parameters, no output schema, and significant operational caveats, the description covers the full lifecycle: what gets registered, which source form to send, what is rejected, size limits, build behavior, workflow differences, return values, and how to follow up on an ongoing build. Nothing an agent needs to invoke this 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 coverage is only 46%, so the description carries real parameter meaning: it clarifies repositoryUrl, ref, archive, files-as-source, preferSource-like fallback behavior, waitSeconds polling, and the source-vs-build distinction. It does not explain every underspecified parameter, but the most consequential decision parameters are given practical, non-obvious semantics.

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

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

The description states a clear, specific process: register if new, attach source, deploy through the application's workflow, and return a live URL or deployment id. It also distinguishes Direct vs Staged routing, so an agent understands exactly what the tool accomplishes beyond its title.

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 explicit when-to-use guidance for the key alternatives: pass repositoryUrl for a pushed git remote, pass archive for local/uncommitted source, send both for fallback behavior, and send neither to redeploy existing source. It also points to springroll.deploy.status for polling and notes that staged applications use explicit promotion and approvals, routing the agent to the right sibling tools.

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

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

The 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 declare readOnlyHint, idempotentHint, destructiveHint=false, so safety is covered. The description adds real behavioral context beyond them: the result set is scoped to the authenticated member and current organization, and results come back newest first, plus a pagination pointer. It stops short of describing rate limits or total counts.

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

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

Two tight sentences, front-loaded with the scope constraint and then the pagination instruction. No filler, nothing redundant with 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?

For a read-only list tool with annotations covering the safety profile and no output schema, the description is nearly sufficient. However, it references 'nextOffset' as a response field the agent cannot see anywhere in the input schema, and leaves limit/offset unexplained, creating a small but real ambiguity about pagination.

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%: the long 'context' description comes from the schema, while limit and offset carry no documentation anywhere. The description's mention of 'nextOffset' loosely gestures at pagination but never explains limit/offset semantics or their bounds, so it does not compensate for the coverage gap.

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

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

States a specific verb (List) and resource (SpringRoll feedback) with precise scope: the authenticated member's own feedback within the current organization. The scope wording implicitly separates it from springroll.feedback.submit, so an agent can pick it without opening 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 implies a read/list use case and gives one operational hint ('Use nextOffset for the next page'), but never states when to prefer this over alternatives or any preconditions. There is no explicit when/when-not guidance, 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?

Annotations already declare the mutation, idempotency, open-world, and non-destructive profile. The description adds value beyond them by warning against including credentials and clarifying retry semantics tied to the idempotency key, though it says nothing about what a successful submission returns 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?

Three short sentences, front-loaded with purpose followed by the two key constraints. Every sentence carries operational value with no repetition or filler.

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

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

For a four-parameter mutation tool with no output schema, the description plus rich annotations cover the safety and retry picture an agent needs. Minor gaps remain around the category values and expected outcome, but the core call path is well specified.

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 25%, so the description must compensate, but it only implicitly illuminates idempotencyKey behavior. It offers no guidance on the category enum values or the message content/length constraints beyond the schema's own bounds.

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 (submit) and resource (bug report, idea, or other feedback) scoped to the authenticated member, which cleanly distinguishes it from the read-only sibling springroll.feedback.list. An agent can identify the tool's operation without opening 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?

Gives actionable context: exclude credentials and reuse the idempotency key when retrying the same submission. It does not name the complementary sibling (feedback.list) or state explicit when-not conditions, so it falls 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?

Annotations already mark this as readOnly, idempotent, and non-destructive, and the description adds that it works before any provider account is connected and that credentials never affect ranking, only deployability. It also explains what the receipt contains, including inferred vs declared attributes and why each candidate lost. This goes well beyond the annotation flags and gives the agent a strong model of side-effect-free 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?

At roughly 130 words, the description is long but well-structured: purpose first, then behavioral guarantees, then usage guidance. Every sentence provides new information—credential independence, receipt contents, what-if use—so it is not padded. It could be tightened 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?

With no output schema, the description compensates by enumerating what the receipt includes: provider, plan, cost range, limits, inferred attributes, and why other candidates lost. It also covers pre-account behavior and readiness/unlock actions per alternative, fully equipping an agent to call it correctly. Nothing essential is missing for a preview-only tool.

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

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

The input schema already documents every parameter with detailed descriptions, so the baseline is 3. The tool description itself only refers generically to 'placement hints' and does not add meaning to individual parameters. This is acceptable because the schema carries the full weight.

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

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

The description opens with 'Scores where SpringRoll would place this application and what it would cost, without deploying or writing anything,' a specific verb, resource, and scope. It explicitly contrasts with springroll.deploy by noting the shared implementation but this tool does not deploy. This makes it clearly distinguishable from every 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?

The description says to use it to put cost and limits in front of the user before deploying or to explore what-if variations, providing strong positive guidance. It does not explicitly name springroll.deploy as the alternative when actual deployment is desired, but the repeated 'without deploying' framing makes that inference immediate. An explicit exclusion would push this to a 5.

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

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

Annotations already declare readOnlyHint, 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.