Upwork MCP Server

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

Annotations only say readOnlyHint=false, but the description goes much further: it declares WRITE OPERATION requiring explicit user confirmation, says each write needs separate confirmation, limits confirmations to file_uids that get_upload_status reports as done, and warns that upload sessions expire in 30 minutes. No contradiction with annotations exists.

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

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

The description is long but every sentence earns its place: purpose first, a prominent safety warning second, and then dense, structured parameter details. No fluff or repetition; the context list and constraints are organized as a single action block.

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 operation's complexity, the description covers prerequisites, timing, exclusions, validity rules, and the confirmation protocol. Even without an output schema, the agent has everything needed to invoke 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?

The schema's params description is generic, leaving the actual required fields undocumented. The description fills this entirely by enumerating valid context values, declaring file_ids and task_id as required, explaining their provenance, and adding the validity constraint from get_upload_status. This is high-value parameter clarification 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 opens with a specific verb and resource: 'Confirm uploaded files so they are retained in Upwork storage.' It further clarifies its relationship to start_attachment_upload and get_upload_status, making it clearly distinguishable from sibling tools.

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

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

Provides explicit decision rules: files uploaded through the inline component are already stored and must NOT be confirmed; confirmation is the step after start_attachment_upload returns file_uid values. It also instructs the agent to ask the user for the context if unclear, and states the 30-minute session urgency.

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

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

Beyond the annotations' destructiveHint=true, the description discloses the mandatory user-confirmation behavior: 'WRITE OPERATION — REQUIRES EXPLICIT USER CONFIRMATION' and 'Each write requires separate confirmation even if user said approve all'. It also clarifies that server-stored params are executed, adding meaningful operational transparency. No contradiction with annotations.

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

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

Every sentence carries useful information, from the core purpose to the explicit exclusion to the user-confirmation requirement. The description is long only because the tool has complex operational constraints; none of the content is 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?

The description covers purpose, prerequisites, exclusions, confirmation behavior, and parameter semantics thoroughly. The only notable gap is that it does not describe the return value or result details after executing a draft, and there is no output schema to fill that 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?

The description adds important draft_id semantics ('from the create draft response', 'executes stored server params only — do not pass confirm payloads') beyond the schema. The type param is thoroughly covered by the schema enum and its description, so little extra description is needed. Overall the description compsensates well for the 67% schema 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 specific verb ('Confirm and execute'), a clear resource ('previously prepared draft'), and lists covered draft types. It explicitly distinguishes itself from offer acceptance by saying 'Do NOT use to ACCEPT an offer', which separates it from sibling workflows.

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

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

It clearly says when to use the tool: after a prior draft action and with a required draft_id. It also gives explicit exclusions: offer acceptance must go through the finalize_url from respond_to_offer, and confirm_draft must not receive confirm payloads. This is strong routing guidance.

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

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

Beyond the annotations, the description discloses the two-phase draft/confirm_draft flow, states that it returns a draft for review, and explicitly warns 'REQUIRES EXPLICIT USER CONFIRMATION.' It also clarifies that this is a write operation, consistent with readOnlyHint=false and destructiveHint=true. This adds substantial behavioral context that annotations alone do not provide.

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

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

The description is well-structured: an opening summary, a workflow note, a warning, and a grouped action/parameter section. It is slightly redundant in mentioning the draft/confirm_draft flow twice, but every sentence carries useful information and the most important warnings are 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 destructive write operation with no output schema, the description fully covers what the agent needs: prerequisites (reason codes via list_contracts), the required flow (returns a draft, call confirm_draft), the required parameters, and the optional review grouping. It leaves no critical gap for safe invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by summarizing the six optional scores and comment, and by stating 'Provide all six scores together for a complete review,' which is a constraint not present in the schema. It also reinforces the source of reason_id and contract_id.

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: 'End a contract with a reason code, optionally attaching a freelancer review.' This clearly distinguishes the tool from the sibling update_contract by describing a terminal action rather than a modification, even without naming the 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 description gives clear usage context: use list_contracts action=end_reasons first to get reason codes, and call confirm_draft after explicit user approval to execute. It does not explicitly describe when to choose this over alternatives like update_contract, but the workflow is well-defined enough that an agent can identify correct usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context on top: skills are AND-matched with ontology-based relaxation and retry, smart_search may return paid placements with boosted=true that must not be presented as earned rankings, earnings are bucketed for display such as "$50K+", and an absent work_history section is explicitly not evidence of no contracts. All of this goes well beyond what annotations alone convey, and nothing contradicts them.

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 very long but well structured: action headings, per-parameter inline annotations, and front-loaded action summaries make it scannable for a complex four-action tool. There is some repetition — "Optional params are refinements" and the personId/profile_key interchange warning appear more than once — but the repeated warnings serve safety-critical routing and most content 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?

With no output schema present, the description carries the full burden of explaining returns, and it does so thoroughly: search results expose personId and profile_key with distinct uses, get_profile returns vendor_org_uid, vendor_org_type, portfolio_available, work_history_available, and work_history_note, and smart_search results specify exactly which fields to present, including boosted_label, organic_position, and preselected_filters. Cross-tool dependencies like obtaining vendor_org_uid before manage_offers create_draft are also covered.

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?

Although schema coverage is 100%, the description adds meaning far beyond the terse schema descriptions. It clarifies that query should be a short role phrase rather than skill keywords, that skills are structured AND-matched facets (not concatenated text), that timezones are Upwork labels rather than IANA names, that smart_search query is a relevance boost not a hard filter, and that job_success_min maps to UI presets 80 and 90. This transforms an ambiguous parameter list into actionable instructions.

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+resource statement — "Search for freelancers and view profiles" — and then breaks the tool into four clearly named actions (search, get_profile, smart_search, smart_search_keywords), each with its own purpose. It also differentiates internal actions from siblings like upwork__find_jobs and upwork__invite_freelancer by scoping exactly what this 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 routing guidance: "Prefer this over find_freelancers action=search whenever the client has a job posting", and marks smart_search_keywords as "SUPERSEDED... use this only when explicitly asked to compare the two rankings." It also explains when not to put terms in both query and skills, when to ask before applying optional filters, and how results should be used downstream (personId for invite_freelancer, profile_key for get_profile, vendor_org_uid for manage_offers).

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

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

Annotations already mark this read-only and non-destructive, but the description adds substantial behavioral context beyond them: there is no created_after/date filter, hire/invite liveness is not in search results, client rating is freelancer-given and should be read as a warning, bid_stats_basis implies unit-less bid amounts, and client_work_history must not be used to derive totals. These caveats directly prevent an agent from misinterpreting responses or inventing unsupported filters.

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 definition is long but well-structured with action headers and dense, purposeful content. Some boilerplate is repeated between search and smart_search—such as the optional-params reminder and several identical filter explanations—which adds length without new information. Still, the front-loaded summary and clear action breakdown make it navigable for an agent.

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

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

With no output schema, the description carries the burden of explaining response semantics, and it does so thoroughly: it documents proposal_count, pageInfo.endCursor, client_record, connects_cost, preferred_qualifications, client_work_history structure, and the meaning of total_spent and rating. It also covers edge cases like access-denied fallback and missing date filters. For a multi-action tool of this complexity, 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 description greatly exceeds the schema's parameter documentation by explaining semantics and pitfalls: budget_min/max apply only to fixed-price jobs while rate_min/max handle hourly rates; duration only constrains hourly jobs; skills are matched exactly and unknown names are reported not guessed; range bounds rules are specified; and cursor pagination requires repeating the same filters. This is exactly the kind of added meaning that helps an agent invoke parameters correctly.

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: 'Search and view marketplace job postings.' It then enumerates three distinct actions (search, get, smart_search), each with a clear function, and explicitly distinguishes this tool from get_job_posting via the fallback instruction. An agent can immediately tell what this tool does and which sub-operation matches a given request.

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 and names alternatives: use smart_search when the user wants profile-matched work, use search for a custom query, use get for full details and preferred qualifications, and fall back to get_job_posting action=get_marketplace on access denied. It also instructs when to ask before applying optional filters, e.g. for selective requests like 'best' or 'near me'. This is strong routing guidance.

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

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

Annotations establish read-only and non-destructive safety; the description adds org_uid-dependent behavior, default-to-current-user semantics for get_user_details, and the marketplace-client redirect. No contradictions with annotations, and no auth or rate-limit details, but for a read-only tool the added context is solid.

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 opens with a one-line summary and then uses a compact action-by-action list. Every bullet adds operational detail without filler or restating the tool name.

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

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

Covers all three actions, their parameters, and the key alternative routing for client accounts. The main minor gap is not describing the return value shape, but with no output schema and readOnlyHint true this is acceptable; the required org_uid is documented in the schema.

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

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

The schema already documents action, params, and org_uid, so the baseline is 3. The description adds value by specifying the optional id default, labeling get_organization and get_company as having no params, and explaining how org_uid selects the account for get_company.

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?

Describes a clear read-only purpose ('View account info and organization details') and enumerates the three concrete operations. It stops short of explicitly distinguishing itself from siblings like list_accounts and update_account, so it gets 4 rather than 5.

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

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

Provides a direct routing rule for get_company: call again with another org_uid for a different account, and use find_jobs action=get for a marketplace job's client. It does not explicitly state when to prefer this tool over list_accounts, but the organization-scoped actions and org_uid requirement imply the intended use 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?

The description adds useful behavioral detail beyond annotations: it checks all activity sources in parallel and requires no action-specific parameters. The readOnlyHint and destructiveHint annotations already establish safety, and the description does not contradict them.

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

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

The description is concise and front-loaded: the first sentence captures the full purpose, and the action bullet is short and useful. Every sentence earns its place without redundancy.

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

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

Given the simple check-only action, read-only annotations, and complete input schema, the description provides enough context for an agent to invoke the tool correctly. It lists what the dashboard contains, though it could be slightly more explicit about the output structure or time window.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the useful clarification that the 'check' action requires no params, but it does not expand on org_uid or other parameter semantics beyond what the schema already provides.

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 purpose: getting a consolidated overview of proposals, pending offers, messages, and contract updates in one call. This distinguishes it from more granular sibling tools like list_client_proposals, get_messages, list_offers, and list_contracts.

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 'all in one call' phrasing implies this tool is for when a broad, consolidated snapshot is needed rather than individual detail calls. However, it does not explicitly name alternatives or state when not to use it, leaving the agent to infer 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 readOnlyHint=true, and the description goes beyond them by disclosing operational traits: transactions may return less than the web page due to accounting-entity scoping, work_diary with no contract_id returns a company-wide view, snapshots return metadata not images, and various defaults/limits. This helps an agent predict actual behavior beyond the annotation flags.

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 action-by-action bullet structure is logical and front-loaded, but the same 'Optional params are refinements' paragraph is repeated nearly verbatim under four actions. This is verbose and could be consolidated. The work_days action is also minimal, so structure is uneven.

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 six-action tool with no output schema and nested params, this description is complete: it defines every action, relevant defaults, caveats, and deprecations. The only notable gap is work_days, which has almost no parameter or result description beyond 'Get work days', and there is no return-format guidance for any action.

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?

Even though schema coverage is 100%, the description adds substantial meaning: date defaulting rules, max 53-week spans, limit behavior, contract_id provenance from list_contracts, paging restrictions, and the snapshot timestamp format. It effectively documents parameters that the schema branches do not cover for work_diary, snapshots, and work_days.

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 clear verb+resource statement ('View client financial reports') and then enumerates six distinct actions, each with a specific verb and scope (summary, timesheets, work_diary, snapshots, work_days, transactions). This distinguishes the tool from siblings and makes the multi-action structure 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?

Provides explicit per-action usage guidance, including when to choose work_diary vs snapshots ('Use work_diary for the diary view; use this only for per-timestamp detail'), and warns that transactions may require elevated org permissions. It also gives default behavior and date constraints, so an agent knows what to invoke and when.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context beyond that: the draft is pending, server-stored, and retrieving it does not consume it. This clarifies the state impact of the call without contradicting the annotations.

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

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

The description is compact and front-loaded: the first sentence states the core behavior, and the Actions section provides the required parameter mapping without extraneous detail. Every sentence contributes to correct invocation.

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

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

For a moderate-complexity tool with nested params and no output schema, the description covers the essential retrieval behavior, the non-consuming nature, and the required draft identifiers. It does not explain the relationship to confirm/update actions, but the schema and annotations cover the remaining operational details adequately.

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

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

Schema description coverage is 100%, and the schema already documents id as 'Draft ID returned as draft_id by the creating action' and type as 'Draft type returned by the action that created the draft.' The description repeats this information rather than adding significant new semantic value, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Retrieve') with a precise resource ('pending server-stored draft') and adds a key scope qualifier ('without consuming it'). This clearly differentiates the tool from siblings like upwork__confirm_draft and upwork__update_draft, which consume or modify drafts.

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 phrase 'Get a pending draft for review' establishes clear context: use this tool when you need to inspect a draft before finalizing it. It does not explicitly name alternatives or when-not-to-use conditions, but the review purpose and non-consuming behavior imply the appropriate usage boundary.

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 readOnlyHint annotation, the description discloses important behaviors: list results are summaries lacking description/budget/skills, applicant counts are included, pagination uses next_page, search results include ready-to-use URLs, and get_marketplace accepts numeric IDs, ciphertexts, or full URLs. It also warns not to silently invent optional filter values. This is rich, non-obvious behavioral context that an agent needs to call the tool correctly.

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

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

The description is well-structured with action-labeled bullets and front-loaded purpose. Some guidance about optional refinements is repeated nearly verbatim under separate actions, adding length, but the repetition reinforces behavior at the point of use. Overall it is dense with useful information and easy to navigate.

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 exposes four distinct actions with nested parameters and no output schema, so the description must compensate. It details list return fields (total_count, has_more, next_page, postings[], applicant counts), search result URLs, get_marketplace URL output, and the relationship between list summaries and get full detail. For a multi-action tool this level of context is complete enough for an agent to invoke 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?

Although the input schema describes parameters, the description adds essential semantics: job_id is preferred and job_posting_id is an alias; marketplace id can be a numeric ID, ciphertext, or full URL; list limit is 1–10 with default 10; page uses next_page; title is a partial-match filter. It also clarifies that optional params are refinements and that the agent should surface rather than invent values. This goes well beyond schema descriptions.

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: 'View your owned job postings and search the marketplace.' It then explicitly differentiates the four actions (get, list, search_marketplace, get_marketplace) and clarifies where to use each, including a direct pointer to find_jobs for marketplace alternatives. This makes the tool's purpose unmistakable and distinct from siblings.

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

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

The description gives explicit when-to-use guidance: use action=list to obtain IDs for list_client_proposals and list_client_invitations; use action=get for full owned-posting details; use get_marketplace for marketplace jobs by ID; use find_jobs for marketplace searches. It also tells the agent when to ask before applying optional filters and how to handle broad user requests, which is actionable routing guidance.

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

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

The description goes far beyond the readOnlyHint by disclosing that room and message counts are unavailable, that messages are newest-first, that hasMore drives pagination, and that message_count only appears after fully reading a thread. These are non-obvious behavioral facts that materially affect agent behavior, and nothing contradicts the annotations.

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

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

The action-based organization is clear and the opening is front-loaded, but the optional-params guidance paragraph is repeated nearly verbatim for list_rooms, search_rooms, and list_messages. Token economy is weaker than the overall quality suggests.

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

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

With no output schema, the description compensates well by explaining response semantics: room cards, newest-first ordering, hasMore, message_count availability, and when not to state totals. It still leaves the exact message/room card field shapes unspecified, which would otherwise be needed for an agent to confidently consume results.

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

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

Schema coverage is already high, so the baseline is 3; the description does add useful aliases, pagination constraints, and per-action required params. However, it contradicts the schema on defaults: list_rooms and list_messages are described as default 10/20 while the schema says default 100, and the 'after' alias for list_messages is not present in the schema. These inconsistencies make the added parameter guidance unreliable.

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–resource summary ('List rooms, find rooms by context, and read messages') and then enumerates five distinct actions with clear semantics. It also differentiates from siblings like send_message and find_freelancers, making the tool's scope 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 gives explicit when-to-use guidance, e.g., 'This is the way to locate an old thread... do NOT use find_freelancers', and instructs paging when summarizing a thread or checking whether something was discussed. It also provides nuanced guidance for optional refinements and proposal-room constraints.

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

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

Annotations already declare readOnlyHint=true; the description reinforces this with 'Read-only' and adds meaningful context: it returns the same From/To range Upwork shows, explains parameter effect, and names return fields. No contradictions with annotations.

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

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

The description is compact and front-loaded with purpose, then gives action-specific parameter and return details. The single-action bullet is slightly redundant with the tool name but every sentence contributes 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?

With no output schema, it correctly documents return fields (rate_low/rate_high, based_on_jobs). It explains the data source ('same range Upwork shows in Budget step') and required parameters. Minor omissions like error/edge-case behavior are not critical for a read-only lookup 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 coverage is 100% and schema descriptions are detailed, so the description doesn't need to compensate. It adds useful mutual-exclusion guidance (one of occupation_id or project_text) and confirms experience_level accepted values, though most parameter meaning is already in the schema.

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

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

Description names a specific operation ('Get the going hourly rate range') and a concrete resource ('similar jobs' / Budget step). It distinguishes itself from sibling tools by tying directly to hourly budget guidance and market rate, so an agent can tell it apart without schema inspection.

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

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

It explicitly says to use this when helping a client set an hourly budget so the suggested rate reflects the market. It doesn't enumerate when-not-to-use or sibling alternatives, but the intended context is clear and the tool appears unique among 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 readOnlyHint=true, so the read-only safety profile is covered. The description adds useful behavioral context about what the call returns—'complete description and input schema'—and the scope of that output, which goes beyond the annotations.

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

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

Every sentence earns its place: the first defines the purpose, the second gives the usage trigger, and the param line clarifies the argument. It is front-loaded with the action and resource, and there is no filler or repetition that could be cut without losing information.

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

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

With a single parameter, a read-only annotation, and no output schema, the description sufficiently explains what the tool returns and when to invoke it. Nothing an agent needs to decide to call this tool 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?

While the input schema already describes tool_name, the description adds critical sourcing guidance: 'the tool to describe (a name from search_tools or the tool list).' This tells the agent exactly where to obtain valid values, which is more helpful than the schema's generic 'Name of the tool to get full help for.'

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: 'Get the full reference for a tool: its complete description and input schema, including every action and all required and optional parameters.' This clearly distinguishes it from all sibling tools, none of which serve a meta-help function.

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 an explicit call condition: 'Call this before using a tool whose listed description is brief and you need the full field list.' It does not name alternative tools, but no alternative exists; a clearer 'when not to use' clause is the only minor omission.

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 readOnlyHint annotation, the description discloses important behavior: upload sessions expire 30 minutes after start_attachment_upload, the response includes file_uid values and metadata, and file content is not returned. These details are actionable and not present in the annotations or 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 compact and front-loaded with the core purpose and key caveats. Minor redundancy exists between the opening sentence and the Actions block, but the structure is clear and every section contributes useful guidance.

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

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

With no output schema, the description adequately explains what the caller will receive: file_uid values and metadata, not file content. It also covers the critical time constraint and the task_id source, making the tool callable without needing to infer hidden behavior.

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

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

Schema description coverage is 100%, so the schema already documents task_id and org_uid. The description adds context about the task_id coming from start_attachment_upload and reinforces the expiry window, but it does not significantly expand on the parameter meanings beyond what the schema provides.

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

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

The description clearly states the tool returns file_uid values for files uploaded through the web UI, using a specific verb and resource. It also disambiguates the action name ('get', not 'get_status') and explicitly notes what the tool does not return (file content), setting it apart from related upload 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 concrete usage context: poll within the 30-minute window after start_attachment_upload, and use action name 'get'. It does not explicitly name alternative tools or when not to use this tool, but the timing and operational instructions are clear enough to guide correct invocation.

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

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

Beyond the annotations, the description clearly discloses that this is a write operation requiring explicit user confirmation and that the tool returns a draft rather than immediately sending. This is critical behavioral information for safe invocation and is not supplied by the annotations alone.

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 and generally concise, with the core workflow in the first two sentences. There is minor redundancy in repeating that confirm_draft must be called after a draft is returned.

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 write operation with multiple actions and nested parameters, the description covers the actual workflow, the confirmation requirement, and points to get_tool_help for the full field list. It could be more self-contained by enumerating the params fields directly, but it is complete enough to guide correct usage.

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 already provides descriptions for action, params, and org_uid, so baseline is met. The description adds useful action-level context for list_jobs and send, but delegates the actual action-specific parameter fields to get_tool_help instead of documenting them.

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

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

The description states a specific action — 'Invite a freelancer to a job posting' — and clearly identifies the resource and outcome. It also distinguishes the tool from the confirmation step by explaining that send only returns a draft that must later be confirmed.

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 workflow guidance: use list_jobs first to check remaining invites, then send, then confirm_draft with type='invitation'. It lacks explicit when-not-to-use exclusions, but the sequencing and reference to get_tool_help provide clear usage context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful scoping context ('your available' accounts) and the sequential behavior 'Call this first', but it does not describe response format, pagination, or auth nuances. It is adequate but not rich.

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?

A single efficient sentence plus a short directive. Every word earns its place: the action, the scope, the account-type enumeration, and the placement instruction. There is no filler or redundant restating of the tool name.

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 parameterless, read-only listing tool, the description is complete enough for correct invocation. It states what the tool returns (accounts), the types it covers, and the recommended call order. No output schema exists, but the description's meaning directly implies a list result, so 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 tool has zero parameters, so the schema vacuously covers 100% of parameter semantics. With no parameters to document, the description need not add parameter details; the baseline of 4 applies and nothing in the description undermines 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 states a specific verb ('List'), a clear resource ('your available Upwork accounts'), and enumerates the account types (Freelancer, Client, Agency). It is easily distinguished from related tools like get_account by the plural 'accounts' and the 'available' qualifier, and 'Call this first' positions it as the intended entry point.

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 instruction 'Call this first' gives explicit, actionable timing context, telling the agent to invoke this tool before others. However, it does not name alternatives or state when not to use it, so it lacks full exclusion guidance.

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

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

Annotations already mark read-only and non-destructive; the description adds pagination details (cursor/pageInfo.endCursor), limit bounds (1–10), invitation_id override behavior, and the source of org (org_uid on execute_tool). It also discloses the expected post-return behavior of mentioning refinements.

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?

Structured with a leading summary then an Actions section; each sentence adds either a constraint, prerequisite, or operational rule. It is longer than average but not bloated given the alias and pagination complexity.

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

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

Covers input aliases, required prior step, pagination, limit, optional param policy, and org resolution. Given there is no output schema, it even hints at the paged return shape via pageInfo.endCursor, so a model has enough to invoke and continue a multi-page list.

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?

Although schema covers all params, the description clarifies aliases (job_id, job_reference for job_posting_id), marks owned-posting-id as required, explains cursor alias 'after', and ties invitation selection to invitation_id. This prevents mis-use that bare schema would allow.

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 opening sentence names the verb ('List or get'), the object ('client job invitations'), and the scope ('for one owned job posting'), which is enough to separate it from sibling tools like list_client_proposals or list_contracts. The follow-up 'there is no list_all' removes ambiguity about aggregate behavior.

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

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

It states the prerequisite ('Requires job_reference from get_job_posting action=list (postings[].id)') and explicitly warns the operation is per-job only. It also gives actionable policy on optional params: do not invent values, ask before applying selective filters, and mention refinements after results.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: declined proposals carry get_unavailable=true and get will not work for them, pagination semantics via pageInfo.hasNextPage and endCursor, jobs_truncated=true meaning the org has more postings than were scanned, and the policy that 'Optional params are refinements: do not silently invent values.' The description also explains the handoff between list_all and list for paging individuals jobs. No contradiction with annotations exists.

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

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

The description is long, but it is tightly organized per action (list, get, list_all, metadata) with each sentence carrying operational value — no filler. Some content is duplicated verbatim across the list and list_all sections (the declined-proposal and refinement guidance), which is slightly redundant, but this repetition is defensible for an agent that may read only one section. The purpose statement is front-loaded before the action details.

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

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

For a four-action tool with a complex conditional schema, no output schema, and significant cross-action interplay, the description covers everything needed: action selection, parameter sources, pagination loops, the declined-proposal edge case, truncation behavior, and refinement etiquette. An agent has enough information to select the correct action, supply correct parameters, and page through all results without additional guesswork.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful semantic value beyond the schema: it explains that job_posting_id comes from get_job_posting action=list, that cursor comes from pageInfo.endCursor of a prior list, the alias relationships (cursor/after, job_id/job_posting_id, id/proposal_id), and the meaning of limit_per_job as a per-job cap. These provenance and cross-tool relationships are not inferable from the schema alone.

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 'View proposals on your job postings,' a specific verb+resource statement. It then clearly delineates four distinct actions (list, get, list_all, metadata) with their own purposes, which distinguishes the tool from siblings like upwork__manage_client_proposals (management vs. viewing) and upwork__list_offers (proposals vs. offers). An agent can immediately tell what this tool does and what each sub-action 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 routing rules: 'Use action=list_all to discover proposals across all postings without a job_posting_id' and 'Use action=list when you already have job_posting_id from get_job_posting action=list.' It also states when NOT to use a feature ('do not call get on their id' for declined proposals) and provides behavioral norms for optional filters, including an explicit 'Ask before applying optional filters' list (best, top, cheapest, near me, urgent, or only). This is exemplary usage guidance.

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

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

Annotations already mark the tool read-only and non-destructive, and the description adds substantial behavioral context beyond that: ID provenance (node.contract.id vs node.id), defaults for vendor_id/organization_id/to_date, pagination cursor/offset semantics, the 'ask before applying optional filters' policy, and the note that get is the authoritative milestone read. No contradiction with annotations.

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

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

The description is long but logically grouped by action, with the main purpose and ID provenance front-loaded. It loses one point for repeating the same optional-refinements paragraph verbatim under multiple actions, which could have been consolidated without losing clarity.

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 output schema, this complex six-action tool is thoroughly specified: input defaults, pagination, response shape hints (node.contract.id, milestones[].submissions[], pageInfo.endCursor), cross-tool ID chaining, and helpful exclusions are all present. There is no significant gap for an agent deciding how and when to call the 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 coverage is 100%, so parameters are already documented; the description goes further by explaining how parameters relate across actions, e.g., ids come from search node.contract.id, contract_id for get comes from search or get, and it adds behavioral constraints like 'at least one date required' and 'max 53 weeks from from_date'.

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+resource ('View and search your contracts and time reports') and enumerates six distinct actions with clear responsibilities: search, list, get, get_original_proposal, timesheets, and end_reasons. This clearly differentiates the tool from sibling tools like list_offers and list_client_proposals by focusing on contracts and associated reports.

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 when-to-use rules: call search FIRST for discovery, use list only for known IDs ('do NOT use for discovery'), use get for full details, and use end_reasons for reason codes. It also routes to related workflows, e.g., manage_milestones action=reject, and warns against inventing optional filters, giving the agent unambiguous selection criteria.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description supplements this with meaningful behavioral details: results are newest first, the org_uid is used automatically, state values are role-appropriate, attachment links are presigned and expire in about 15 minutes, and optional params should not be silently invented. No contradiction exists between description and annotations.

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

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

The description is well-structured with action-based bullets and front-loaded guidance. However, the list and list_mine sections duplicate the same parameter details and refinement policy nearly verbatim, which adds length and some redundancy. Still, the structure makes the multi-action tool easier to navigate.

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 multi-action read-only tool with no output schema, the description is complete: it covers action selection, parameters, source of identifiers, output behavior, attachment link expiry, role-specific state lists, and guidance on optional refinements. No critical information an agent needs to call the tool correctly is missing.

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

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

Although the input schema already covers 100% of parameters, the description adds substantial semantic value: it explains where offer_id comes from and what it is NOT (clientOffers node.id), lists role-specific state values for clients vs freelancers/agencies, clarifies the relationship between id and offer_id, and warns against passing unsupported parameters like searchAttribute. This goes well beyond the schema alone.

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 purpose ('View and list offers') and enumerates distinct actions (get, get_attachments, list, list_mine) with specific verbs and resources. It also differentiates internal actions and references the sibling context, e.g., 'For active contracts prefer list_contracts action=get', making it easy for an agent to select the right operation.

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: 'Use list_mine to see all offers for your org', 'Use get to fetch full details of a specific offer', and 'For active contracts prefer list_contracts action=get'. It also instructs the agent not to pass forbidden params and how to handle optional refinements, including asking before applying selective filters. This is strong, actionable routing guidance.

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

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

The description goes well beyond annotations by disclosing that this is a confirmation-gated write operation requiring explicit user approval for each action. It also explains the decline workflow's draft/confirm_draft step and clarifies that shortlisting does not hire, all of which are non-obvious behavioral details.

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 section adds value: scope, confirmation requirement, action-specific details, and routing to sibling tools. The critical write-confirmation warning is prominent, and the action details are organized in scannable bullets.

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 params object and lack of an output schema, the description provides complete guidance for using the tool correctly. It covers both actions, required and optional parameters, the confirmation obligation, the decline draft follow-up, and the distinction from hiring.

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?

Although the input schema is generic with a params object, the description thoroughly documents every action-specific parameter: proposal_id, job_posting_id, shortlisted, reason, and message. It explains defaults and optionality, such as shortlisted defaulting to true and the reason being auto-matched.

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 manages proposals on job postings with two specific actions: shortlist/un-shortlist and decline. It explicitly distinguishes itself from a hiring action by directing the agent to use manage_offers create_draft for proposals that should become offers.

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 context: managing proposals while reviewing applicants. It also provides a clear alternative: if the intent is to hire or accept a proposal, use manage_offers create_draft instead. This removes ambiguity about sibling tool selection.

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 mark the tool destructive and non-readonly; the description adds important contextual behavior: draft-based actions require confirm_draft, explicit user confirmation is needed, and money-moving actions return a link. There is slight ambiguity in 'Returns a draft for review' because it could be read as applying to all six actions even though the prior sentence clearly carves out the link-returning ones.

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, front-loaded with the verb and resource, and every sentence adds operational value. The caps warnings and the pointer to get_tool_help are structurally effective without unnecessary 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?

The description covers the essential write flow, the special money-moving exception, how to check milestone state when reads are needed, and where to obtain action-specific parameters. The only soft spot is the slightly ambiguous draft-return statement, but overall it provides enough context for an agent to proceed 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 covers the three top-level parameters, and the description adds meaning to the action enum by explaining that create/edit/delete/reject produce drafts for confirm_draft while activate/approve return links and move money. The params object itself remains opaque, but the description explicitly routes the agent to get_tool_help for the full field list.

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 explicitly states 'WRITE milestone management' and enumerates the precise operations: create, edit, delete, reject, activate, approve. It distinguishes the money-moving actions from the draft-based ones and explicitly says there are no list/get actions, making the tool's 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?

The description gives explicit when-to-use and when-not-to-use guidance: use it for milestone writes, but inspect milestone state via list_contracts action=get. It also explains that activate and approve return a link for completion on Upwork rather than a draft, and points to get_tool_help for detailed usage.

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 only indicate readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds meaningful behavioral context beyond these: it explicitly warns that this is a write operation requiring user confirmation and that draft creation must be finalized by the user on upwork.com. This is valuable for agent decision-making and does not contradict the annotations.

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

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

The description is concise and well-structured: a purpose sentence, a critical warning, and a pointer to detailed help. The write operation warning is front-loaded, which is appropriate for a non-read-only tool. 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?

This is a multi-action tool with nested params and no output schema. The description gives the essential warning and directs the agent to get_tool_help for exhaustive action and parameter details. It does not enumerate action semantics or return values, but the explicit pointer to help and the schema enum mitigate that gap for a complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema for parameters; it only points to get_tool_help for the full field list. It does not explain action-specific parameter semantics, but the schema already documents each parameter at a basic level.

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+resource: 'Create draft offers and manage offers to freelancers.' This identifies the tool's domain and primary action. However, 'manage offers' is broad and does not explicitly distinguish this tool from siblings such as list_offers or get_draft, though the action enum provides some scope.

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 important usage context: it is a WRITE OPERATION requiring explicit user confirmation, and created drafts must be finalized on upwork.com. It also tells the agent to call get_tool_help for actions and parameters. However, it does not state when to prefer this tool over alternatives like list_offers or get_draft, nor when those siblings are more appropriate.

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

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

The description adds substantial behavior beyond annotations: starts with a prominent WRITE OPERATION — REQUIRES EXPLICIT USER CONFIRMATION directive with per-operation approval semantics, notes that the default Favorites list is auto-created, discloses eventual consistency for newly saved freelancers, and states what list_lists returns. No contradiction with destructiveHint=true or readOnlyHint=false.

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

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

The description is long but earned by a seven-action surface; the purpose statement and write-warning are front-loaded, and each action occupies a single dense line. Minor redundancy exists (the tool title is restated as 'Your Lists'), but nothing is empty 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 multi-action tool with no output schema, coverage is strong: all params documented, cross-tool references included (find_freelancers, list_accounts), edge cases covered (auto-created Favorites, delayed visibility). The only gap is that return shapes are specified only for list_lists, not for the mutation actions.

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?

Though top-level schema coverage is reported at 100%, the params object is only conditionally documented for list_talents; the other six actions rely on the description for parameter meaning. The description compensates by specifying required vs optional, defaults, ranges, omit-to-use-Favorites semantics, and ID provenance (list_id from list_lists, freelancer_id as personId), exceeding the baseline.

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+resource statement — 'Save freelancers to your talent lists, create lists, and browse the freelancers in a list' — and then enumerates seven concrete actions with distinct semantics. It differentiates from siblings like find_freelancers, invite_freelancer, and manage_offers by focusng on the talent-list domain.

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 action-level context and practical routing: freelancer_id is sourced from find_freelancers, and list_talents includes a note to use lists_for_talent for an immediate check. It lacks an explicit 'when not to use' alternative at the tool level, but the per-action guidance is concrete enough to steer correct selection.

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?

This description goes well beyond the annotations. It discloses that the tool is a WRITE OPERATION requiring explicit user confirmation, that it does not post directly but returns a draft for review first, and that skills are 'resolved automatically' from human-readable names. These are critical execution traits an agent cannot infer from readOnlyHint=false or destructiveHint=true alone, making the two-step draft/confirm behavior and the confirmation gate genuinely valuable 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?

The purpose is front-loaded in the first sentence and the high-stakes confirmation warning is prominently placed. However, the draft/confirm workflow is stated twice in near-identical terms ('For create, returns a draft for review before posting. Use confirm_draft to publish after approval' and 'Returns a draft for review — call confirm_draft to execute after explicit user approval'), which is redundant and could be consolidated into a single sentence.

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

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

For a multi-action, destructive tool with an opaque nested params object and no output schema, the description covers the essential ground: the create workflow, the confirmation requirement, and the skill format. It explicitly points to get_tool_help for the missing action/parameter detail. The main gaps are that close/close_reasons actions are never mentioned and the expected return shape beyond 'a draft' is unspecified, though the help pointer mitigates these.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds one useful semantic detail — skills should be given as human-readable names and are auto-resolved — which the schema's generic 'Action-specific parameters' line lacks. However, the params object itself remains opaque, with its full field list externalized to a get_tool_help call; the description acknowledges this delegation but does not compensate for the gap.

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

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

The description opens with a specific verb+resource, 'Create or update a job posting,' which is concrete and identifiable. It distinguishes itself from the sibling publish step by naming confirm_draft ('Use confirm_draft to publish after approval'). However, the tool's action enum also includes close and close_reasons, which the description never surfaces, leaving the stated purpose slightly narrower than the tool's actual scope.

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 establishes a clear workflow: this tool creates or updates a posting and returns a draft, and confirm_draft is the designated follow-up for publishing. This effectively routes the agent between post_job and confirm_draft without ambiguity. It also directs the agent to get_tool_help for full details. It stops short of naming alternatives for reads (get_job_posting) or drafts (get_draft/update_draft), so inversion guidance is partial.

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

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

Beyond annotations (readOnly=false, destructive=true), it discloses that every write requires explicit confirmation, auto-creates rooms, consumes limited new connections, depends on attachment upload, and supports message editing. No contradiction with annotations.

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

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

Well structured with front-loaded constraints and clear action bullets, but the message-limit and file-attachment caveat is repeated verbatim four times, adding unnecessary length.

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 multi-action write tool with no output schema, it covers prerequisites (RoomCreateInputV2, attachment upload, org_uid), role restrictions, per-action params, side effects, and an important response detail (remaining_connections). Nothing essential to selecting or invoking the tool 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 only has generic action/params/org_uid fields; the description specifies all action-specific parameters, requiredness, the message length limit, attachment file_id/file_name/image_id requirements, and job_posting_id behavior. This greatly exceeds the schema's 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 first sentence states the operation verb and resource ('Create rooms and send messages') and the body enumerates five distinct actions, so an agent can identify what the tool does and how to pick an action. It also contrasts proposal-room initiation with replying in existing rooms, which further separates it from related message and proposal 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?

Provides explicit when and when-not guidance: freelancers cannot initiate proposal rooms or send the first proposal message; if no room exists, tell the user the client must message first; reply via list_freelancer_proposals/get_messages. It names the alternative tools and also mandates separate confirmation per write.

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

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

The description clearly discloses that set is a write operation, requires explicit user confirmation for each write, and takes effect on the next tool call or tools/list request. These behavioral details go well beyond the annotations, which only indicate non-read-only, non-idempotent, non-destructive hints.

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

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

The description is well-structured with a clear purpose, prominent write-operation warning, and bulleted action list. There is slight redundancy between the 'WRITE OPERATION — REQUIRES EXPLICIT USER CONFIRMATION' header and the following sentence restating the same requirement, but the overall structure is efficient.

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 description provides everything needed to call the tool correctly: the two actions, the mode values, the required confirmation behavior, and the timing of effect. It does not describe the expected return shape, but there is no output schema and the invocation details are sufficiently complete for an agent.

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?

Although the input schema has 100% description coverage for its top-level properties, the nested params object is generic and does not enumerate the mode parameter. The description fills this critical gap by specifying mode as a required string with allowed values 'full_list' or 'search_execute', and also clarifies that get requires no params.

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 'views or changes how MCP tools are presented' and explains the two presentation modes, full_list and search_execute. This precisely distinguishes it from related tools like set_tool_permission, which concerns permissions rather than presentation mode.

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 context on when to use get vs set, and explains the practical difference between the two mode values. It does not explicitly compare against alternative tools, but the purpose is specific enough that an agent can infer when to invoke 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?

Beyond the annotations, the description discloses that this is a write operation requiring explicit user confirmation, that each write needs separate confirmation even after 'approve all,' and that it does not bypass the separate confirm_draft flow for destructive writes. This is substantive, safety-critical behavioral context that the annotations alone do not provide.

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

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

The description is front-loaded with the purpose, then gives usage context, a clear safety warning, and a compact action list. Every sentence contributes either to selecting the tool, invoking an action, or avoiding unsafe behavior; there is no filler or redundancy that weakens the guidance.

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 description covers purpose, usage boundaries, safety requirements, and action-specific parameters, which is strong. It does not describe return values or the response shape for get/set, and there is no output schema, but the core calling decisions and safety constraints are complete enough for an agent to act 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?

The top-level schema only describes action, params, and org_uid generically, but the description adds the missing nested parameter details: tool_name optional for get and required for set, plus the permission enum 'always_ask'/'always_allow'. It does not repeat every schema field, but it substantially clarifies the action-specific parameters 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 opens with a specific verb-resource pair: 'View or change per-tool write confirmation settings.' It immediately distinguishes the tool from siblings by naming the exact domain (write confirmation settings) and breaks it into get/set actions, so an agent can tell what it does and how it differs from other Upwork 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?

It gives explicit when-to-use guidance: set 'always_allow' for automated flows, and explains the default 'always_ask' state. It also provides when-not/limitations: 'This applies in search_execute mode only' and 'it never bypasses the draft-confirm gate,' making the boundary of use clear.

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

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

Annotations are all neutral/negative (readOnlyHint=false, idempotentHint=false, etc.), so the description carries the full burden and delivers richly: write-operation confirmation policy, short-lived session, size limits, conditional context requirement, polling requirement, return values, and expiry behavior. Nothing contradicts the annotations.

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

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

The description is long but every section earns its place given the tool's conditional schema and write-operation stakes; the core purpose is front-loaded and the WRITE OPERATION warning is prominent. The only flaw is minor redundancy: the 'ask the user for context rather than guessing' instruction appears both in the opening paragraph and again in the Actions section.

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 output schema, the description explains all return values; it fully covers the complex conditional schema (context enum + room_id requirement), the write-confirmation policy, size limits, session expiry, and the post-upload polling lifecycle. Everything needed to correctly select and invoke this tool is present.

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?

Although schema coverage is 100% (baseline 3), the description adds substantial meaning beyond the schema: it explains each context enum value (messages = room attachments requiring room_id, proposals = job-application attachments, etc.), specifies that room_id is required only for messages and sourced from get_messages list_rooms, clarifies reason is optional, and documents the return fields task_id, fallback_url, and expires_at.

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: 'Requests a secure file upload from the user. Creates a short-lived upload session and returns task_id plus fallback_url.' It clearly differentiates from siblings like confirm_attachment_upload, get_upload_status, and store_uploaded_files by centering on session creation rather than confirmation, status, or storage.

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?

Extensive when-to-use guidance: it distinguishes the inline UI (7 MB) from the fallback_url (100 MB/file, 300 MB total) and says to use the fallback for larger files; it dictates when to ask the user for context rather than guessing; it names the follow-up flow via get_upload_status; and it gives the 30-minute expiry restart rule. It even includes an anti-pattern warning: never ask for base64 text or local file paths.

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 carry the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description is consistent with them: 'persists' describes a non-read-only, side-effecting write. It adds beyond-annotation context by disclosing the app-only invocation scope and that the model is not an actor, which is the principal behavioral fact an agent needs. It does not elaborate on re-call side effects, but idempotentHint=false already signals that.

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, front-loading the most decision-relevant fact ('App-only') and delivering the prohibition ('The model does not call this tool') immediately. Every word earns its place.

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

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

For a tool the agent must never invoke, the description carries both facts that matter — what it is and that the model must not call it — while the schema covers task_id sourcing from start_attachment_upload. It does not map the upload lifecycle (start → store → confirm) to its siblings, but that is largely unnecessary given the explicit no-call directive. A small deduction for not naming the lifecycle siblings, which would help an agent reason about the upload flow.

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 67%: task_id and org_uid are documented, while files lacks a property-level description. The description adds only indirect parameter context by tying the files to the inline UI session, and does not compensate for the undocumented files payload. This is a middle score — the schema does most of the parameter work, and the description neither repeats it nor fills the 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 ('persists') with a precise resource ('files uploaded through the inline MCP App UI') and a scope restriction ('App-only'). This clearly differentiates it from siblings like confirm_attachment_upload or get_upload_status, which manage upload state rather than storing file payloads.

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 when-not guidance: 'The model does not call this tool.' It also identifies the invocation context — files uploaded through the inline MCP App UI — which tells the agent this is an app-internal persistence step it must never select. This is the strongest possible routing guidance for a tool the model is prohibited from calling.

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?

It prominently discloses that this is a WRITE OPERATION requiring explicit user confirmation, and that it returns a draft for review rather than executing directly, with confirm_draft as the execution step. These behavioral traits go beyond the annotations, which only mark readOnlyHint=false, destructiveHint=false, and idempotentHint=false.

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 warning 'WRITE OPERATION — REQUIRES EXPLICIT USER CONFIRMATION' appears verbatim twice, adding unnecessary redundancy. The core information is front-loaded and readable, but the duplication prevents a higher score.

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 description covers the full workflow: precondition (get_account), parameter guidance (only changed fields), the draft return, and the subsequent confirm_draft step. Although the exact params object structure is deferred to get_tool_help, that pointer is explicit and acceptable given the availability of the help 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 coverage is 100%, so the baseline is 3. The description adds meaning by naming the updatable fields ('company name, description, and business location') and instructing to pass only the fields to change, which complements the opaque params object in the schema. It also points to get_tool_help for the full field list, further aiding parameter understanding.

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 'Update your own company account: company name, description, and business location,' using a specific verb, resource, and scope of changes. This clearly distinguishes it from sibling tools like update_contract and update_draft, which target other resources.

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

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

The description gives clear operational context: call get_account action=get_company first, pass only the fields to change, and follow up with confirm_draft after approval. It does not explicitly list exclusions or alternative tools for other updates, but the 'own company account' scope makes the intended usage 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?

The description goes well beyond the annotations by disclosing that this is a write operation requiring explicit user confirmation, that it returns a draft rather than executing immediately, and that update_hourly_limit returns a finalize_url without changing the limit. It also notes the freelancer notification.

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

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

The description is well-structured and front-loaded: a one-line summary, a critical write-operation warning, and a bulleted action list with per-action parameters. Every sentence contributes decision-relevant information without unnecessary padding.

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 adequately covers return behavior (draft or finalize_url), the external Upwork step, required parameters per action, and the confirm_draft execution path. An agent has enough context to invoke the tool correctly.

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

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

The input schema provides generic params object descriptions, but the description adds essential action-specific parameter semantics: pause and restart need contract_id and message, while update_hourly_limit needs only contract_id. This directly helps the agent construct correct invocations.

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 purpose with a specific verb and resource ('Update contract conditions') and then enumerates three concrete actions: pause, restart, and update_hourly_limit. This makes it easy to distinguish from related tools like confirm_draft or update_draft.

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: pause and restart produce drafts requiring confirm_draft, while update_hourly_limit is not a direct change and requires the user to complete it on Upwork. This gives actionable routing and execution guidance.

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

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

Goes well beyond the annotations by disclosing write semantics, mandatory user confirmation, per-write confirmation even after 'approve all', draft_id invalidation, merge-vs-replace behavior, and the fact that nulls in content are ignored. This gives the agent critical operational knowledge that annotations alone do not provide.

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

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

The description is front-loaded with the essential purpose and the write-confirmation warning, then structured as an executable action list. There is some redundancy around re-approval and new draft_id, but the length is justified by the tool's nuanced invalidation and confirmation flow.

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 description covers the full lifecycle relevant to this tool: what changes, how merging works, how to remove fields, what the response contains, why the old draft_id is invalid, and how to proceed with confirm_draft. Even without an output schema, the agent has enough to call the tool correctly and handle 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: id is the draft_id and is invalidated by the edit, content is a partial merge, mode can replace the whole payload, and remove_fields is the only way to delete fields. This is a useful supplement to the schema's already-detailed parameter descriptions.

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 action: 'Change the content of a pending server-stored draft without executing it.' This clearly identifies the verb, resource, and scope, and distinguishes it from sibling tools like confirm_draft and get_draft by emphasizing the edit step and explicitly ruling out execution.

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

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

Provides clear context for when to use the tool: editing a pending draft before confirmation. It also explains the relationship to confirm_draft and warns that edits invalidate prior approval, which guides sequencing. It does not explicitly enumerate alternatives such as get_draft, but the main workflow implication is strong enough.

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