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

With no annotations provided, the description carries the full burden and meets it well. It discloses the irreversible side effect ('MINTS A CONTRACT'), the human commitment ('This is a commitment to a person, not a draft'), and the financial scope ('It commits no money on its own'). These are exactly the behavioral traits an agent needs to know before calling 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?

The description is three sentences, front-loaded with the core action and side effect, followed by the most important caveats. Every clause adds value: scope, commitment severity, and the funding distinction. There is 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 tool with no output schema and no annotations, the description is remarkably complete. It covers the side effect, ownership prerequisite, human-commitment warning, and the fact that funding is handled later by a separate tool. An agent has enough context to invoke it correctly and avoid misuse.

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 both parameters fully, including weeklyLimit's meaning as 'Optional cap on billable hours per week, for hourly contracts.' The description adds no additional parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Hire a bidder: accepting a proposal MINTS A CONTRACT and returns it.' It states the core object transformation (proposal → contract) and explicitly ties the tool to the HIRE scope. This clearly differentiates it from siblings like freelance_submit_proposal and freelance_fund_milestone.

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

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

It gives clear context for use: the posting must be your organization's, and this is a real commitment rather than a draft, so confirmation is needed first. It also explicitly routes the next step to a sibling: 'funding happens later... through freelance_fund_milestone.' This tells the agent both when to use the tool and when to defer to an alternative.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It usefully discloses that the contract must be owned by the organization and that no money is committed, which prevents misuse as a payment action. However, it does not mention required permissions, contract status constraints, side effects, or what happens after adding the milestone.

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

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

The description is three concise sentences with no redundancy. The definition is front-loaded, followed by ownership scope and the key money caveat. Every sentence earns its place.

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

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

For a create-like tool with no annotations and no output schema, the description covers the most important operational context: who can use it, ownership of the contract, and the fact that no payment occurs. The remaining gaps, such as contract status requirements or response details, are minor and don't block correct tool selection.

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 adds conceptual meaning by framing the milestone as a 'named piece of work' with an amount and due date, which maps to the input properties. However, the schema already provides descriptions for id, title, amount, and dueDate, and the description adds little beyond that, especially for the contract id and date format.

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 ('Add a milestone to a contract') and defines what a milestone is: a named piece of work with an amount and due date. It also distinguishes itself from sibling payment actions by noting it 'commits no money,' which clearly separates it from fund_milestone and related tools.

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

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

The description gives clear context: client lane, contract ownership requirement, and HIRE scope. The 'commits no money' statement implies this is for the pre-payment setup stage, but it does not explicitly name alternatives such as freelance_fund_milestone or provide when-not-to-use conditions.

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

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

With no annotations provided, the description carries full burden. It discloses the irreversible, money-moving nature, the acknowledgment requirement, the error response, and the per-call scope of the flag. This is exemplary behavioral transparency.

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 dense but front-loaded with the most critical warning, and every sentence adds value. It is longer than typical but justified by the high-stakes, irreversible nature of the operation.

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 complexity (irreversible money movement), the lack of annotations, and no output schema, the description is thorough. It covers when to use, prerequisites, error handling, and consent semantics, leaving no critical gaps.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds crucial context for 'acknowledge', explaining its meaning and conditional requirement, which goes beyond the schema. The 'id' and 'milestoneId' are straightforward and don't need extra description.

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

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

The description clearly states the tool approves submitted work and moves milestones through statuses, specifically releasing escrow on funded milestones. It distinguishes this from siblings like submit_milestone and fund_milestone by focusing on the approval and payment 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 explains when to use the tool (on submitted or funded milestones) and provides critical guidance on the acknowledge flag, including when not to use it. It also references sibling tools implicitly by contrasting with funding and refunding.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It strongly discloses the most critical behavioral trait: the posting is immediately visible to real people and can be bid on by freelancers, and it instructs agents to confirm details with a human before calling. It also states the organizational-token requirement. It does not cover failure modes, reversibility, or editability, but the most consequential side effect—public exposure—is well communicated.

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

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

The description is three sentences, each earning its place: purpose and scope, the organizational prerequisite, and the safety warning with a specific visibility tip. The most important fact—immediate public visibility—is front-loaded and appropriately emphasized with capital letters. There is no fluff 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?

The tool has a complex nested schema, but the schema itself documents the nested fields. The description fills the non-obvious contextual gaps: the organization-token requirement, the real-world visibility consequence, and the use of `visibility: ORGANIZATION` for internal work. It does not describe return values, but there is no output schema, so that is not required. It could mention cross-field dependencies (e.g., fixedBudget only with FIXED_PRICE), but those are already in the schema descriptions, so the description is sufficiently complete.

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

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

Schema description coverage is 0% for the top-level 'input' parameter, so the description must compensate. It does for one key parameter: it explains the consequence of `visibility: ORGANIZATION` (keeping the job internal), which goes beyond the schema's simple enum listing. However, it adds no meaning for the many other nested fields, relying on their in-schema descriptions. This partial compensation warrants a 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 clearly states the action with a specific verb and resource: 'Publish a job posting to the marketplace under your organization's name.' It distinguishes the tool from the many read/search siblings in the list by emphasizing creation/publishing, and it also conveys the key organizational context—this tool operates on behalf of an organization, setting it apart from proposal/submission tools.

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

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

The description gives clear context and prerequisites: it belongs to the HIRE scope and requires an organization context on the token, explicitly noting that a personal token has nothing to post as. It also provides actionable guidance—confirm title, budget, and description with the user before calling, and use `visibility: ORGANIZATION` to keep the job internal. It does not name alternative tools, but no other sibling serves the same create-job purpose, so the context is sufficient.

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

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

With no annotations provided, the description carries the full behavioral burden and handles it well: it discloses that money leaves the spendable balance, is HELD as the organization's but not spendable and not the freelancer's, and is reversible while the work is unapproved. This is unusually clear about state changes and side effects.

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 dense and front-loaded, leading with the money-movement effect, then prerequisites, then reversibility. The opening 'MOVES MONEY.' is slightly redundant with the next sentence, but every remaining sentence earns its place.

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

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

For a financial mutation tool with no annotations and no output schema, the description covers the critical context: prerequisites, error behavior, escrow semantics, and reversibility. It does not describe the success response or return value, which is a minor gap given the command-like nature of the operation.

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

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

Schema coverage is 100% and the parameter descriptions in the schema already identify the contract id and milestone id. The tool description adds context about the milestone's amount and escrow, but it does not explain the relationship between the two IDs or add parameter-specific semantics beyond the schema.

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

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

The description states a specific verb and resource: 'Commit a milestone's amount to escrow before the work starts.' It also distinguishes itself from the sibling refund tool by naming freelance_refund_milestone and clarifying the forward-vs-return direction of the money movement.

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

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

It gives an explicit temporal trigger ('before the work starts'), states a hard prerequisite (SPEND scope), and tells the agent exactly what to do on failure: the fix is a human granting the scope, not a retry. It also says no acknowledgement flag is needed because the operation is reversible, which guides interaction design.

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

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

With no annotations provided, the description carries the full burden and does meaningful work: it discloses the required permission, the membership constraint, and the financially significant escrowStatus FUNDED behavior. It does not explicitly state that the tool is read-only, but 'get' and 'by id' make that largely implicit.

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

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

The description is two sentences with no filler. The core purpose is front-loaded, and the warning about funded milestones earns its place by preventing a costly mistake.

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 one-parameter, read-only retrieval tool with no output schema, the description is complete: it names the return content, states the required access, and adds the critical approval caveat. Nothing needed to call it 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 100% and the only parameter, id, is already described as 'The contract id.' The description adds no further parameter-level detail, which is acceptable because nothing more is needed for a single unambiguous identifier.

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: 'One contract by id, with its milestones and their escrow state.' This clearly distinguishes it from sibling list and action tools, and the mention of milestones and escrow state identifies the unique payload this tool returns.

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

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

The description gives a clear use context: read this before approving milestones, and it names the prerequisite READ_OWN and membership. It does not explicitly contrast with freelance_list_contracts, but the 'by id' wording makes the selection obvious.

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

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

With no annotations provided, the description carries the full behavioral burden, and it succeeds. It discloses the non-obvious side effect that reading a conversation "MARKS IT READ for this account," which clears the other side's unread signal, and it emphasizes that the alternative tool has no such effect.

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 purpose, then adds the critical side-effect warning and routing guidance. Every sentence earns its place, and there is no wasted wording.

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

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

For a simple two-parameter tool with no output schema, the description provides everything an agent needs to decide whether and how to invoke it: the resource, the permission requirement, the side effect, and the correct alternative when summarising an inbox. Nothing essential 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?

The input schema fully describes both parameters: id as the conversation id and limit as the number of messages returned newest first. The description itself adds no additional parameter-level detail, so the baseline of 3 for full schema coverage is appropriate.

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

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

The description states the exact resource: "One thread and its messages." It clearly identifies the operation as retrieving a single conversation thread, and the contrast with freelance_list_conversations in the usage note differentiates it from the closest sibling.

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 says when not to use this tool: "Do not sweep every thread to summarise an inbox unless the person asked you to." It names the alternative, freelance_list_conversations, and explains why it should be used instead because "unread counts" from it "change nothing."

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the READ_DIRECTORY requirement, server-side re-authorization, per-org visibility rules, and explains that an empty result for an inaccessible ORG posting is expected behavior rather than an error.

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

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

Two sentences, front-loaded with the core purpose. The second sentence is dense but earns its place by explaining authorization and failure semantics; it could be tightened slightly but contains no filler.

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

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

For a single-parameter read tool with no output schema, the description covers id usage, permission requirements, visibility filtering, and empty-result meaning. An agent has enough information to select and call it correctly and to interpret unusual results.

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

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

The only parameter 'id' is already fully described in the schema, so schema coverage is 100%. The description adds general context but no new syntax, format, or value semantics for the id beyond confirming it selects one posting.

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 begins with a specific action and resource: 'One job posting in full by id.' This immediately distinguishes it from sibling list/search tools and tells an agent exactly what resource it targets.

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 by 'by id' – an agent can infer to use this when it already holds a posting id rather than when searching/filtering. It does not explicitly name alternatives or state when not to use it, though it does give a prerequisite: READ_DIRECTORY.

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

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

No annotations are provided, so the description must carry the burden. It discloses that it returns owner-only fields (email, listing status) and requires the READ_OWN permission. It also clarifies that it acts on behalf of the token's identity, which is a key behavioral trait. While it doesn't mention rate limits or response format, the critical aspects are covered.

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

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

Two sentences, efficiently structured. The first sentence states the purpose and key fields; the second provides usage guidance. No fluff, and the most important information (what it returns) 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?

For a zero-parameter tool with no output schema, the description provides all necessary context: what it returns, the permission required, and when to use it. It is fully sufficient for an agent to call it correctly and interpret the result.

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

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

The tool has zero parameters and the schema is empty with 100% coverage, so there is nothing to explain. The baseline for 0 parameters is 4, and the description adds no parameter-related details because none are needed.

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 verb 'get' and the resource 'my profile' (the freelancer profile of the authenticated token). It distinguishes itself from sibling tools like freelance_get_profile by specifying it returns the profile belonging to the account the token authenticates as, including owner-only fields. This makes it unambiguous.

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

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

Explicitly instructs to use this tool first to confirm which account and organization the token is acting for, and notes that every other tool acts as this identity with no argument to redirect. This provides clear when-to-use context and implicitly explains why alternatives like freelance_get_profile (which likely targets arbitrary profiles) are not appropriate for identity confirmation.

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

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

No annotations are provided, so the description carries the full burden, and it delivers meaningful behavioral context: 'READ_DIRECTORY' discloses the authorization requirement, and 'public projection' reveals that the response excludes private data (contrasting with get_my_profile). It would be stronger with error behavior for invalid ids, but provenance guidance mitigates the main failure case.

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 zero waste: the core action is front-loaded first, followed by the projection qualifier, permission requirement, and id provenance — each clause earns its place. The contrast framing for the name-vs-id warning is especially economical.

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 one-parameter get-by-id tool with 100% schema coverage and no output schema, the description covers what it returns (public projection), who may call it (READ_DIRECTORY), and how to obtain valid ids. Return-value details are only hinted at ('public projection'), but the self-evident nature of a profile retrieval makes this a minor gap.

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

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

Schema coverage is 100% (the schema already describes id as 'The freelance profile id'), so baseline is 3. The description adds real value beyond the schema by specifying the valid id source ('Ids come from freelance_search_talent') and explicitly ruling out name lookups — this materially improves the agent's chance of supplying a valid parameter.

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

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

The description states a specific retrieval action ('One freelancer from the directory by id') with the resource clearly named. It differentiates from siblings: 'as the public projection shows them' distinguishes it from freelance_get_my_profile, and 'by id' separates it from freelance_search_talent. The purpose is unambiguous.

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

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

Provides explicit, actionable guidance: 'Ids come from freelance_search_talent' names the prerequisite sibling tool, 'Requires READ_DIRECTORY' states the permission gate, and 'a name is not an id, and there is no lookup by name' is an explicit when-not warning against the most likely misuse. This is exemplary routing and exclusion advice.

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

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

With no annotations provided, the description carries full responsibility. It explicitly states 'A READ - it moves nothing,' discloses the required permission (READ_OWN), and explains the behavior of related funding refusal, giving the agent a complete picture of side effects.

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

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

Three sentences, each earning its place: the first states the resource and contents, the second adds the permission and read-only nature, the third provides a concrete usage hint. No fluff, well 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?

Despite no output schema, the description enumerates the returned fields (toSpend, toCashOut, inEscrow, ledger entries). It also covers the usage context and constraints, making it fully self-sufficient for a zero-parameter 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 tool has zero parameters, so the description has no parameter explanations to add. The baseline for zero parameters is 4, and the description correctly avoids unnecessary parameter detail.

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

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

The description states a specific resource (wallet) and what it returns: funds available to hire, earnings, escrow, and ledger entries. It clearly distinguishes from sibling tools which are unrelated to wallet operations.

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 instructs to check toSpend against a milestone amount before calling freelance_fund_milestone, explaining the consequence of insufficient funds. This provides clear when-to-use guidance and points to an alternative tool.

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

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

With no annotations provided, the description carries the full burden. It discloses the permission requirement (READ_OWN) and the behavioral nuance of the role filter (default returns both sides), which is valuable. It does not describe pagination, return shape, or side effects, but as a read-only list operation, the most critical behaviors are covered. Lacks detail on what happens with no matches or how limit/offset interact, but these are not essential.

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

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

The description is three sentences, each earning its place: the purpose, the permission, and the filter guidance with a warning. It is front-loaded with the core definition and avoids redundancy. No filler or vague phrasing.

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 nested filter object, 5 parameters, no output schema, and no annotations, the description provides essential context: the account scope, the permission, and the role semantics. It does not mention pagination or default limit behavior, but these are adequately described in the schema. The description is sufficient for an agent to decide when to use this tool and how to construct a meaningful query.

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 adds significant meaning to the 'filter.role' parameter beyond the schema: it explains that FREELANCER means work the account is doing and CLIENT means work it is paying for, and warns about the default behavior. Other parameters (limit, state, offset, jobPostingId) have clear schema descriptions, so the description doesn't need to expand them. Since the most confusing parameter is fully explained, the description compensates for the low overall coverage.

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

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

The description states a clear verb ('list') and resource ('contracts') with a precise scope: contracts where the account is either freelancer or client organization. It explicitly names the two roles and contrasts with the likely sibling 'freelance_get_contract' by focusing on the plural list behavior. This leaves no ambiguity about what the tool does.

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 guidance: it states the required permission (READ_OWN), instructs to pass `filter.role` to select a side, and warns that omitting it returns both, which is 'rarely what a question means.' This tells the agent exactly when and how to use the filter, and implicitly directs to alternatives like get_contract for a single contract.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the permission requirement ('Requires READ_OWN'), the return content ('unread counts'), and the thread-identity concept (anchors). It does not explicitly confirm read-only behavior, pagination, or ordering, but the permission and unread-count details add useful 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 sentences, each earning its place: purpose and key data, permission, and disambiguation. The anchor explanation is dense but directly relevant to avoiding confusion between similarly named threads. 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 zero-parameter list tool with no nested objects or output schema, this is fairly complete: it states the permission, the returned data (threads with unread counts), and the anchor concept that addresses a common ambiguity. It only omits minor details like pagination or ordering.

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 tool has zero parameters with 100% schema description coverage, so there is nothing for the description to add about parameter syntax. Instead, it contributes conceptual value by explaining thread anchors, which helps an agent interpret the listed results.

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

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

The description clearly names the action ('list') and resource ('Message threads this account takes part in'), and adds the unread-count detail. It explains thread anchors for distinguishing conversations, but it doesn't explicitly contrast with the sibling freelance_get_conversation, so the distinction is inferred rather than stated.

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

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

The description implies its usage context: listing all conversations for the current account, versus viewing a single conversation or sending messages. However, it never explicitly says when to prefer this over alternatives like freelance_get_conversation, nor does it state exclusions.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It adds valuable context by explaining the INVITED status ('a client pulled this account into a posting and nobody has bid yet') and the READ_OWN permission requirement. While it doesn't detail pagination or sorting behavior, it discloses the two distinct result types (bids and invitations), which is a meaningful behavioral trait.

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

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

The description is two concise sentences with no filler. It front-loads the core scope, then adds a permission note and a domain clarification. Every sentence earns its place.

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

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

For a list tool with no output schema and no annotations, the description is fairly complete: it explains what is returned (bids and invitations), the permission needed, and the key status nuance. It does not describe the return format or default ordering, but the filter schema and the simple list nature make this a minor 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%, but the schema itself provides solid descriptions for limit, offset, status, and jobPosting. The description adds semantic value for the status parameter by clarifying what INVITED means, which is directly useful when using the status filter. It does not elaborate on the filter object or other parameters, but those are self-explanatory from 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 precisely identifies the resource and scope: 'The bids this account has placed, and the invitations it has received.' This clearly distinguishes it from sibling tools like freelance_list_proposals_for_job, which targets proposals for a specific posting rather than the account's own activity. The tool's purpose is immediately understandable.

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 states the scope ('this account') and implies the tool is for viewing one's own proposals and invitations. However, it does not explicitly say when to use this tool versus alternatives, nor does it mention any exclusions or conditions. Usage is inferred rather than directly guided.

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

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

With no annotations provided, the description carries full behavioral disclosure. It reveals an auth requirement, an invariant that the recipient is always taken from the token and cannot be overridden, and the effective requirement on `side`, which schema would otherwise mark as optional.

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 dense but every sentence earns its place: identification, ordering, auth, recipient sourcing, and side semantics. It is front-loaded with the most identifying information and contains 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 purpose, ordering, auth, the recipient invariant, and effective parameter requirements, with `limit` documented in the schema. The main gap is that, with no output schema, it does not describe what a notification object looks like or what a caller should expect in the response.

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 gives `side` meaning beyond the enum, explaining what each lane represents and why omitting it produces a useless merged feed. It does not discuss `limit`, but the nested schema already documents its default and cap, so the main parameter ambiguity is resolved.

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

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

The description clearly identifies the resource as 'this account's own notification feed' and states the ordering ('newest first'). This distinguishes it from other list tools in the sibling group, such as list_my_proposals or list_org_jobs.

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 gives a prerequisite (READ_OWN) and explains when to use each side lane: FIND_WORK for bid-related notifications and HIRE_TALENT for requisition-related ones. It warns that a merged feed answers neither use case, though it does not explicitly contrast with 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?

With no annotations provided, the description must carry the full burden. It discloses the READ_OWN permission and the inclusion of ORGANIZATION-visibility postings, which is useful. However, it does not mention read-only nature, pagination behavior, or any potential side effects, leaving some ambiguity for a list operation.

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

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

The description is two sentences, front-loads the most important scoping detail (own organization, includes ORGANIZATION-visibility), and states the permission and use case. There is no wasted text.

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 list tool with a single filter parameter and no output schema, the description covers the key elements: what it returns, who can use it (READ_OWN), and when to use it (before reading proposals). It does not specify return format or error handling, but these are reasonably inferable from the tool name and schema, so it is mostly 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 description does not discuss parameters, but the input schema provides detailed descriptions for each sub-property of the filter object (e.g., sort, limit, offset, search, status, category). While the top-level filter lacks a description, the schema effectively documents the parameters, so the description adds no extra meaning but does not need to; baseline 3 is appropriate.

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

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

The description clearly states the tool lists the organization's own job postings, including ORGANIZATION-visibility ones the public search never returns. It uses a specific verb ('list') with a clear resource ('org jobs') and distinguishes itself from the public search, making its purpose unmistakable.

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 explicit guidance: use it to find the posting id before reading proposals, and implies it is for the hiring side's internal list. It contrasts with the public search but does not name an alternative sibling tool like freelance_search_jobs, so a slight deduction.

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

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

With no annotations, the description carries the full burden. It clearly indicates the operation is a read (listing) and discloses the permission (READ_OWN) and the refusal behavior for unauthorized postings. This gives the agent important behavioral context beyond the schema.

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

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

The description is two sentences with zero fluff. The core purpose is front-loaded, and the access constraint is stated clearly and efficiently. Every word adds value.

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

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

The tool is simple (1 parameter, no output schema). The description covers the purpose, the permission, and a critical error case (refusal for unauthorized postings). The lack of an output schema means it need not explain return values, but one could argue it might mention that the list returns proposals with their statuses, but that's not critical for calling it correctly.

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

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

Schema description coverage is 100%, so the single parameter is already documented as 'The job posting id'. The description adds no further detail on the parameter syntax or format, which is fine given the high coverage. The description's behavioral notes don't directly relate to the parameter, so a baseline of 3 is appropriate.

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

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

The description clearly states that it lists all bids on an organization's job posting, framing it as the 'hiring side's applicant list'. It uses a specific verb ('list') and resource ('proposals for a job') and immediately distinguishes it from related tools like freelance_list_my_proposals, which would be the freelancer's view.

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 the requirement: the posting must belong to the caller's organization, and it warns that asking about another's posting is refused, not filtered. This provides clear guidance on when to use the tool and the access constraints, though it doesn't explicitly name 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the tool moves money, requires the SPEND scope (enforced by the server), is reversible (funding restores it), carries no acknowledgement flag, and is a decision about someone's pay that should be confirmed before calling. This is rich, honest disclosure of side effects and prerequisites.

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

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

The description is front-loaded with 'MOVES MONEY' and is concise at four sentences. It efficiently conveys purpose, prerequisites, reversibility, and a caution. The note about the acknowledgement flag is an internal detail but still relevant. No wasted words, though the aside about the flag could be seen as slightly extraneous; overall it is well-structured.

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

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

For a financial tool with two parameters and no output schema, the description covers the key operational aspects: what it does, the required scope, reversibility, and a warning to confirm. It does not detail return values, but that is not required without an output schema. The context is sufficient for an agent to decide when to call it and what to expect.

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

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

Both parameters (id and milestoneId) are fully documented in the schema with descriptions ('The contract id' and 'The milestone id'), giving 100% coverage. The tool description adds no additional meaning about how these parameters are used or how they relate to the refund operation. Per the rubric, baseline 3 is appropriate when schema covers parameters fully and the description does not augment it.

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

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

The description clearly states the action: 'Take escrowed money back out of a milestone and return it to the organization's spendable balance'. This is a specific verb (refund) and resource (milestone), and the opening 'MOVES MONEY' signals a financial mutation. It also distinguishes itself from siblings by emphasizing the condition 'while nothing has been handed over', which differentiates it from approve_milestone or fund_milestone.

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 usage with 'while nothing has been handed over', indicating the tool is for refunding escrowed funds before delivery. However, it does not explicitly state when to use this tool versus alternatives like fund_milestone or approve_milestone, nor does it provide explicit 'use when / use instead' guidance. The condition is implied but not fully 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?

Since no annotations exist, the description carries the behavioral burden. It discloses the public marketplace scope, the open status, and the required permission READ_DIRECTORY. It does not describe the response shape or pagination behavior, but those are reasonably inferable for a search tool and covered partially by schema 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 three sentences with no filler. The purpose is front-loaded, the permission follows naturally, and the sibling distinction closes it. Every sentence earns its place.

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

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

Despite having no annotations and no output schema, the description covers scope, permission, and routing to the correct sibling tool. The main omissions are response format and explicit pagination expectations, but those are minor for a read-oriented search tool and the schema supplies limit and offset semantics.

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 itself adds no filter-specific guidance, and the top-level parameter has no prose description, making schema coverage 0%. However, the nested filter object's properties are individually well-described in the schema, which offsets most of the gap. The description could have summarized key filters but is not fatally deficient.

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 and object: 'Search open, publicly visible job postings across the whole marketplace.' It also identifies the exact scope ('FIND WORK side') and distinguishes itself from freelance_list_org_jobs, so there is no ambiguity about what the tool does.

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 states when to use the tool: to find bid-able, publicly visible marketplace work. It also gives an explicit exclusion and alternative: 'for your own organization's requisitions ... use freelance_list_org_jobs instead.' It additionally provides the permission prerequisite READ_DIRECTORY.

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

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

With no annotations, the description carries the full burden. It discloses that only the public half of profiles is returned, excludes contact details and verification documents, and mentions the READ_DIRECTORY permission. It also hints at the over-constraining behavior. It does not cover error handling or rate limits, but the key behavioral traits are covered.

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

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

The description is four sentences with no fluff. It front-loads the core purpose, then adds the permission requirement, return projection, and a practical usage tip. Every sentence earns its place.

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

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

Given there is no output schema, the description explains the return projection (public half, no contact/verification docs) and the permission requirement. It does not detail pagination defaults or error scenarios, but the filter includes limit/offset and the over-constraining tip covers a common failure mode. Overall, it is adequate for a search 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%, meaning the description text adds no parameter meaning. However, the input schema itself provides detailed descriptions for each filter property, so the baseline is 3. The description only advises omitting the filter entirely, which is a usage tip rather than semantic explanation.

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 searches the talent directory for freelancers available to hire, which differentiates it from sibling tools like freelance_search_jobs. It also specifies the return scope (public half of profiles), making the purpose unambiguous.

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

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

The description gives explicit usage advice: omit the filter to see all listings and warns about over-constraining city or skills. It does not name alternative tools, but the purpose is distinct enough that an agent can infer when to use it. The mention of READ_DIRECTORY requirement adds a precondition.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly warns 'NOTHING UNDOES THIS' and that the recipient is notified, which is critical for an irreversible send action. It also discloses that the message is sent under the account's name, a key behavioral detail.

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 dense but efficient, front-loading the core action and then layering warnings and usage rules. Every sentence adds value: purpose, scope, irreversibility, approval requirement, and addressing syntax. No fluff or 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 send-message tool with no output schema, the description covers all necessary aspects: what it does, how to target the recipient, the irreversible nature, and the human-approval requirement. It even explains how to anchor a new thread. The description is fully self-sufficient.

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 adds substantial meaning beyond the schema. It explains the mutually exclusive addressing logic ('EITHER with conversationId... OR with exactly one of...'), which the schema alone does not convey. It also clarifies the required message field. Given the schema coverage signal of 0%, the description fully compensates.

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 precise verb and object: 'Send a message to a real person, under this account's name.' It clearly distinguishes itself from sibling conversation-list/retrieval tools by emphasizing the send action and the irreversibility. The mention of 'MESSAGE scope' and the explicit 'no edit and no delete' further delineate its unique 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 provides explicit usage guidance: it requires user confirmation before sending ('get a yes before calling'), clarifies that drafting is fine, and specifies exactly how to target a thread via either conversationId or one of the four anchored IDs. This is superior guidance that goes beyond basic when-to-use, including a safety rule.

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

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

With no annotations, the description carries the full burden. It discloses the state change, the role prerequisite, and the social consequence ('puts the client on the spot'). It also provides an ethical caution. This is strong coverage, though it could mention whether the action is reversible or triggers notifications.

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

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

Two sentences, front-loaded with the action and state change, followed by role and caution. No redundancy or filler. Every sentence earns its place.

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

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

For a simple tool with two parameters and no output schema, the description covers the core purpose, role requirement, and behavioral consequence. It is sufficiently complete for an agent to decide when to call it, though it could hint at post-submission workflow (e.g., client approval) for extra context.

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

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

Schema description coverage is 100% with both parameters described as 'The contract id.' and 'The milestone id.' The description adds no additional meaning beyond what the schema provides, so it remains at the baseline 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 clearly states the tool's action: 'Hand a milestone in for review, moving it PENDING -> SUBMITTED.' It identifies the resource (milestone), the action (submit), and the state transition, making it easy to distinguish from siblings like approve_milestone or fund_milestone.

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 specifies the freelancer lane and the requirement that the account must be the contract's freelancer. It also warns against calling without the freelancer's say-so, which is a clear usage constraint. However, it does not explicitly name alternative tools or provide a when-not-to-use scenario beyond the role restriction.

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

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

With no annotations provided, the description carries the full behavioral burden, and it does so impressively. It warns that the cover letter reaches a real person as words the account wrote, mandates prior approval, and states concrete refusal conditions. This discloses the most consequential external effects and failure behavior, which is exactly what an agent needs before invoking a high-stakes bid.

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 dense but every sentence earns its place: purpose, scope, human-impact warning, approval requirement, prerequisite read, and refusal conditions. The most important operational warning is front-loaded before the prerequisite details, and there is no filler or repetition of schema 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 complex submit action with no output schema and no annotations, the description is largely complete: it explains the human consequence, required precondition, conditional requirements, and failure behavior. It does not mention the requiredLinks/links condition or the success response shape, but those are partially covered by the schema, so the remaining gap is minor.

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 outer description adds meaningful context for coverLetter and rate by explaining the cover letter is read as the account's words and both text and rate must be human-approved. However, it does not elaborate on currency, rateType, estimatedDuration, links, or answers, and schema description coverage is reported as 0%, so the description only partially compensates. The nested schema fields do carry their own descriptions, which keeps this at a minimally adequate 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 states a concrete action ('Bid on a job posting'), names the resource ('in this account's name'), and identifies the scope as PROPOSE. This clearly distinguishes it from siblings like freelance_create_job, freelance_accept_proposal, and freelance_list_my_proposals, so an agent can tell what the tool is for at a glance.

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: read the posting first with freelance_get_job, answer every applicantQuestion, send acknowledged: true when acknowledgments exist, and get human approval for the cover letter and rate before calling. It does not explicitly enumerate alternatives or say 'do not use when...', but the bid-scope and prerequisites make the intended usage clear enough.

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