Scope by Ouroboros Apps

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds real value beyond them by explaining what destruction means here ('may discount a rate or add work') and by enforcing the human-approval gate as a behavioral precondition.

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

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

Three short sentences, front-loaded with the action and its condition. The final sentence slightly restates the approval requirement already implied by sentence one, a minor 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?

An output schema exists, so return values need not be explained. The description covers the critical precondition and the consequence of calling it, which is sufficient for a three-parameter mutation tool, though parameter-level detail remains thin.

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

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

Schema description coverage is 0%, so the description must compensate. It gives useful semantics for 'confirmed' (must be true, and only after approval), but says nothing about engagementId or changeOrderId beyond their presence, leaving two of three parameters undocumented.

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 ('Apply one proposed change order') and scopes it to a single order, which clearly separates it from file_change_order and approve_scope. An agent can distinguish it from siblings without opening any schema.

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

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

Explicitly states the precondition: only call after the freelancer explicitly approves, and 'Pass confirmed true only then.' It also warns that calling it is not a substitute for approval. It does not name an alternative sibling to use when approval has not occurred, which keeps it short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds non-annotation context: the action commits a 'current draft' to an approved state, and the confirmed flag is a deliberate human-approval gate, which meaningfully warns against premature invocation.

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, zero filler, and the action statement is front-loaded ahead of the invocation guard. Every clause earns its place.

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

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

An output schema exists so return values need no explanation, and the write-action semantics plus the approval precondition are supplied. It could be slightly richer about irreversibility (whether an approved scope can be reopened or superseded), but for a 2-parameter action it is close to 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?

With 0% schema description coverage, the description carries the burden, and it does explain the semantic intent of 'confirmed' (an explicit-approval signal) beyond the bare const:true constraint. 'engagementId' is left unaddressed, but its UUID name is self-explanatory, leaving only a minor 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+resource ('mark the current draft as the approved scope') that is distinct from the sibling approve_change_order. An agent can tell exactly which artifact is being approved 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 an explicit precondition: only pass confirmed=true after the freelancer explicitly approves items, rates, and deadlines. That is strong usage guidance, though it never names the alternative tool (approve_change_order) for the change-order case, so it stops short of full when/when-not routing.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the safety bar is pre-covered. The description adds genuinely useful state semantics: the result is a DRAFT and not a commitment until approve_scope runs. That is real context beyond the annotations, though permissions and idempotency behavior are not addressed.

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

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

Two tight sentences with zero waste, and the core action ('Create a draft engagement') is front-loaded before the state caveat.

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?

An output schema exists, so return values need not be explained, and the draft/approval workflow is captured. However, for a 4-parameter creation tool with 0% parameter documentation, the description leaves the inputs semantically unexplained, which is a 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 0% across 4 parameters, and the description adds no meaning for title, summary, currency, or clientName. The schema only supplies structural constraints (required, pattern, maxLength), so the semantic burden falls entirely on the description, which does nothing here.

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

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

States a specific verb and resource ('Create a draft engagement') and distinguishes itself from the approval sibling by framing the output as a draft, explicitly referencing approve_scope. It does not differentiate from the other creation/save siblings (save_rate, save_deadline, save_scope_item), which keeps it from a 5.

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

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

Usage is only implied through the workflow note that draft terms are not an approved commitment until approve_scope, which suggests this is the first step before approval. There is no explicit when-to-use/when-not guidance and no direct comparison against the save_* or list siblings.

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 this is a non-read-only, non-destructive, non-idempotent write. The description adds meaningful context beyond that: the operation records a proposal only and deliberately leaves scope, rates, and deadlines untouched. It does not describe the downstream approval flow or what the call returns, but the critical side-effect boundary is disclosed.

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?

Opens with the core action, immediately bounds the behavior, then lists per-kind requirements. Every sentence earns its place with no 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?

With an output schema handling return values and annotations covering the safety profile, the description supplies the purpose, the behavioral boundary, and the conditional parameter rules an agent needs to invoke it. Minor omissions (relationship to approve_change_order, engagementId) are tolerable given the surrounding structured data.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does so well by enumerating the conditional per-kind requirements (add_work, discount_rate, add_rate, move_deadline) that the flat schema cannot express. It adds little on the always-required engagementId/summary or the meaning of amountMinor ('lower'), leaving some gaps.

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 ('Record a proposed change order') and clarifies it is a proposal, not an application. This implicitly distinguishes it from the sibling approve_change_order, though it never names that sibling explicitly.

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 statement 'does not change scope, rates, or deadlines' signals when this tool is appropriate versus the direct-mutation siblings (save_rate, save_deadline, save_scope_item), giving clear context. It stops short of explicitly naming those alternatives or stating when-not to use it.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real semantic value: only this record is quotable, draft status is not a commitment, and proposed change orders authorize neither discounts nor extra work. This tells the agent how to interpret returned data, not just that the call is safe.

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

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

Four short, front-loaded sentences with no filler; the core 'read the approved record' instruction leads and the caveats follow. Everything earns its place, though the imperative tone reads more like policy than tool documentation.

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?

An output schema exists so return values needn't be explained, and annotations cover the safety profile; the description fills the remaining interpretive gaps (approved vs draft, proposed vs authorized). The only real omission is documenting the engagementId parameter.

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

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

The schema has 0% description coverage on the single required parameter (engagementId), so the description carries the burden of compensation and provides none. It never states what the id identifies or what format is expected, adding nothing beyond the schema's type declaration.

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 (read/get) and a well-defined resource: the approved scope, rates, deadlines, and change orders for an engagement. The 'approved' qualifier meaningfully separates it from write-side siblings like approve_scope, file_change_order, and save_rate, though no sibling is named explicitly.

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?

'before answering' and 'Quote only this record' imply the usage context (consult this to answer authoritatively), and it warns that draft status and proposed change orders are not binding. But it never states when to prefer a sibling tool or what to do instead, leaving the agent to infer alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower. The description adds meaningful context beyond that: results are scoped to the authenticated freelancer's own engagements, and ids are authoritative rather than guessable. It does not cover pagination 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 short, front-loaded sentences: purpose first, then downstream usage, then the prohibition. Zero filler and nothing repeated from the schema or annotations.

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?

An output schema exists, so return values need not be described, and annotations carry the safety profile. The description covers purpose, ownership scoping, and the follow-up tool. The only real gap is that the offset parameter and pagination behavior go unexplained.

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

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

There is one parameter (offset) with 0% schema description coverage, so the schema alone does not explain it. The description says nothing about pagination or the offset, so it fails to compensate for the coverage gap, though the single optional param with a default keeps the impact small.

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), a specific resource (engagements), and the ownership scope (the signed-in freelancer's), which distinguishes it from create_engagement and the get/save siblings. An agent can identify the tool 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 explicit downstream workflow guidance – feed a returned id to get_approved_record – and a clear prohibition (do not guess an engagement). It names the consumer tool but does not state when this tool should be avoided in favor of another listing path.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the agent knows this can overwrite state and is not repeat-safe. The description adds that this is scoped to a single scope item and that 'move' implies replacing an existing deadline, but says nothing about permissions, whether a prior deadline is lost, or what happens on an unknown scope item.

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

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

Two tight sentences with the action front-loaded and the format detail second; nothing is redundant or padded.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. However, for a destructive mutation on a required scopeItemId/engagementId pair with no parameter descriptions, the definition is thin on preconditions and side effects.

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

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

Schema description coverage is 0%, so the description must compensate and it only does so partially: it explains dueOn's calendar-day YYYY-MM-DD semantics, which the schema already conveys via pattern. engagementId and scopeItemId are left entirely undocumented in both the schema and the description, which is a real gap for a 3-required-parameter tool.

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 pair ('set or move') and resource ('the deadline') scoped to 'one scope item', which separates it from siblings like save_rate and save_scope_item by resource. It is clear and actionable, though it does not explicitly name a sibling or state a boundary against them.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of the approval-related siblings (approve_scope, approve_change_order) that might gate deadline changes. 'Set or move' implies the intent, but the agent is left to infer all context.

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

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

Beyond the destructiveHint and idempotentHint annotations, it discloses concrete business rules: lower amounts are treated as discounts and refused, unit changes are refused, and new codes after approval are refused. These refusal semantics are not derivable from annotations or schema and materially affect whether a call succeeds.

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

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

Three short sentences, each earning its place, with the core action and its constraints front-loaded before the pointer to alternatives. No 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?

An output schema exists so return values need no explanation, and the description fully covers the mutation's state logic and refusals. The only gap is that the 5 required parameters lack semantic detail, consistent with the 0% schema coverage.

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

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

Schema description coverage is 0%, so the description carries the burden, but it only implicitly references amount, unit, and code without explaining amountMinor's minor-unit format, the code/label roles, or the UUID engagementId. Most of the 5 parameters remain undocumented in any field.

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 pair (set/update) and resource (rate), and splits behavior into draft vs approved cases. It also names the routing target (file_change_order, approve_change_order), letting an agent distinguish it from siblings 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?

It states exactly when to use this tool (set draft, update approved without lowering/unit change) and when not to, explicitly naming the alternative tools for the excluded cases. Both the inclusion and exclusion conditions are unambiguous.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the bar is lower. The description still adds non-obvious policy behavior: post-approval additions and renames are rejected, which tells the agent when a call will silently fail. It does not cover auth/permission requirements or rollback of an update.

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

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

Three short sentences, front-loaded with the action and followed by the two refusal conditions. No filler; every clause conveys a constraint the caller needs.

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

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

An output schema exists, so return values need not be explained, and the refusal rules cover the trickiest behavioral edge. However, with four parameters and zero schema coverage, the description omits which fields identify an existing item versus create a new one, leaving a meaningful gap for a destructive mutation tool.

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

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

Schema description coverage is 0% across four parameters (engagementId, title, description, scopeItemId), and the description supplies no field-level meaning at all. The only faint hint is that 'renaming' maps to title, leaving engagementId, scopeItemId and description undocumented in both places.

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 pair and resource: "Add or update a scope item the freelancer has accepted." That is clearly distinct from approve_scope or file_change_order, though the differentiation is implied by the refusal rules rather than stated as a contrast.

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 real when-not guidance: new items are refused after approval until approve_change_order adds the work, and renaming approved work is refused. It names the alternative tool for the post-approval path, though it never states positively when to reach for this tool versus save_deadline or save_rate.

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