flconsole — Upwork jobs

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

Adds substantial context beyond the annotations: alerts:false means nothing runs server-side, alerts:true makes the Telegram bot notify on every match, and each mode caps at 5 feeds. It also discloses the user_confirmed guardrail. It stops short of describing the returned object, but the safety-relevant behavior is well covered.

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

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

Front-loaded with the core purpose before the mode detail. It is long, but nearly every clause carries operational weight (mode differences, limits, approval flow); a touch of density keeps it from a 5.

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 nested-filter creation tool with no output schema, the description covers modes, limits, approval requirements, and ai_filter application semantics. An agent has everything needed to call it correctly and safely.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds meaning: it clarifies base.q is required, explains what ai_filter is for (relevance criteria structured filters can't express) and how user_confirmed must reflect in-conversation approval. Genuinely additive over the schema.

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

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

States a specific verb and resource ("Save a feed: a named search (filters + ai_filter + your agent_notes)") and ties it to the sibling it feeds ("reuse with find_jobs(feed_id)"). An agent can distinguish it from list_feeds, update_feed, and set_feed_alerts without opening schemas.

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

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

Explicitly explains the two modes and when to use each: "Use alerts: true only when the user explicitly asked for Telegram notifications," and notes alerts can be toggled later via set_feed_alerts. It also prescribes the approval workflow (show search, filters, ai_filter; get approval; pass user_confirmed: true).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds important procedural context: explicit user approval is required and the user is notified in Telegram. It could say more about irreversibility, but the safety workflow is well disclosed.

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

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

The description is three short sentences with no wasted language. The destructive action and required approval step 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 two-parameter tool with complete schema coverage and destructive annotations, the description provides the essential approval and notification context. It does not describe the deletion result or confirm irreversibility, but the available structured fields cover most needs.

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 both feed_id and user_confirmed are already documented. The description reinforces the approval protocol for user_confirmed but adds little parameter meaning beyond the schema.

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

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

The description states a specific verb and resource: "Delete a feed." It also clarifies that deletion applies regardless of whether alerts are on or off, which distinguishes the action from alert/pause 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?

It gives a clear pre-call workflow: name the feed to the user, get approval, then pass user_confirmed: true. It does not explicitly mention alternatives such as set_feed_paused or update_feed, but the destructive context is clear.

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

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

The description goes far beyond the annotations by disclosing cursor persistence, quota and rate limits (60s/100 jobs per hour/1000 per day), filter-too-broad rejection behavior, skipped_count, paused-feed responses, and the exact output shape and ordering. These are concrete behavioral constraints an agent could not infer from readOnlyHint=false or destructiveHint=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?

Despite its length, the description is front-loaded with purpose and source selection, then organized into numbered RULES and a final LIMITS line. Every sentence carries operational value, and no filler or redundant restatement of schema fields is present.

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

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

For a complex nested-filter tool with no output schema, the description supplies the missing return format, cursor behavior, error cases, rate limits, and agent-judgment workflow. An agent has everything needed to call it correctly and interpret the response.

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

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

Schema coverage is high at 83%, so the baseline would be 3, but the description adds critical semantics: exactly one source must be chosen among filters/feed_id/all_feeds, cursor must be passed back only with filters, and feeds keep their cursor server-side. It also tells the agent to put every user criterion into filters, which is meaningful guidance beyond the nested schema fields.

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 ('Find new Upwork jobs') and immediately distinguishes its role as a search/monitoring tool from get_job_details, which it says should be used only for in-depth review. An agent can identify the tool's function and primary alternatives without opening any schema.

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

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

It explicitly enumerates the three mutually exclusive modes (filters, feed_id, all_feeds), states which is the default, explains when to ask the user for criteria, and directs the agent to get_job_details only for a few jobs worth showing in depth. It also spells out rate limits and what to do when filters are too broad.

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

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

Annotations already cover readOnlyHint and openWorldHint, so the safety profile is known; the description adds value beyond that by disclosing the rate-limit trait ('no hourly quota') and the intended downstream use of results. Not exhaustive, but genuinely additive context rather than a restatement.

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

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

Three short, front-loaded sentences: what it finds, how to use the result, and the operational caveat. Nothing redundant, and the highest-value information (matching rule) comes first.

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

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

With one simple parameter, no output schema, and annotations covering safety, the description supplies nearly everything needed: matching semantics, examples, and result usage. Minor gap is that it does not say what the returned location values look like (code vs. name), which matters for filter construction.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: the single 'query' parameter is a substring match against names or aliases, illustrated with 'united' and 'EU'. Length bounds are only in the schema, but the core matching semantics are explained.

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

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

States a specific verb and resource (find locations) and narrows the scope to client countries, subregions and regions, plus the matching rule (name or alias substring). No sibling tool overlaps this resource space, so an agent can select it unambiguously.

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

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

Gives clear context for use ('Use the returned values in filters as base.location') and concrete example queries, so the agent knows the intended workflow. It stops short of naming alternatives or stating when not to use it, but no sibling competes for this task.

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 openWorldHint=false, so the description's 'Read-only' is a restatement, but the added 'no hourly quota' and the instruction to follow saved personal_instructions are genuine behavioral context not in the annotations. It does not discuss error behavior or freshness/caching of the returned context, which is the main remaining gap.

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 directive 'Call this FIRST' is front-loaded, which is exactly right for a session-bootstrapping tool. The single long sentence stuffing five return groups into one string is dense but every clause carries information; only minor readability loss from the run-on structure.

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 full burden of explaining return values, and it enumerates them (base_instructions, skills index fields, enablement, personal_instructions, feeds with their sub-fields, feed limits). For a zero-parameter read tool this is as complete as an agent needs.

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 takes zero parameters, so the baseline is 4 and the description has nothing to disambiguate. It adds no spurious parameter guidance, which is correct.

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

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

The description names a concrete resource — server context, base instructions, skills index, user settings, feeds — and states exactly what each returned section contains. It is clearly distinguishable from siblings like get_skill and get_usage because it explicitly delegates skill loading to get_skill.

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

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

It gives an unambiguous invocation rule: 'Call this FIRST in every session.' It also names the follow-up alternative ('load the one for the task with get_skill'), so the agent knows both when to call this and what to call next.

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 openWorldHint=false, and the description consistently adds useful behavioral context: the default window, the 7-day cap, and that it has no hourly quota. It also provides a rich inventory of returned data, though it does not discuss permissions or error behavior.

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

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

The description is dense and front-loads the purpose, then packs the report contents efficiently. It is a long run-on sentence, which slightly hurts readability, but almost every phrase carries concrete information about the report.

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

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

There is no output schema, but the description compensates by enumerating the major returned fields and their semantics, including source values and tuner change attribution. Combined with complete parameter coverage and clear safety annotations, it gives the agent enough to call 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?

Schema description coverage is 100%, so both parameters are already documented. The description reinforces the meaning of 'since' and its default/limit, but does not materially extend parameter semantics beyond the schema, so it stays at 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 states a very specific report scope: what a feed did since a time, with an explicit enumeration of contents (jobs sent, opened, thumbs, ai_skipped, alerts, tuner state, recent changes). This clearly distinguishes it from operational siblings like create_feed or find_jobs and from usage/quota 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 implies when to use it by defining the report window and noting it is read-only with no hourly quota. However, it does not explicitly contrast the tool with siblings such as get_usage, get_job_details, or find_jobs, so the agent must infer the best alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description layers on genuinely new operational constraints the annotations do not carry: a hard cap of 5 upwork_id per call and a throttle of 30 jobs per hour. Disclosing rate limits and batch ceilings is precisely the context annotations cannot convey.

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

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

Three compact sentences, front-loaded with what data is returned, then when to use it, then operational limits. The field enumeration is long but each item is informative; no filler or repetition.

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

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

With no output schema, the description still tells the agent what comes back, where the input IDs must come from, when the tool is appropriate, and the rate/batch limits. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the single parameter and its 1-5 array bounds are already fully documented in the schema, establishing the baseline of 3. The description restates the 'Up to 5 upwork_id per call' bound and the find_jobs provenance, which is mildly reinforcing but adds no new syntax or format meaning.

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

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

States a specific verb+resource ('Full data of jobs') and enumerates exactly what the payload contains (experience level, duration, workload, category, client statistics). It explicitly positions itself relative to the sibling find_jobs by scoping to jobs that tool already returned, so an agent can distinguish the two without opening a schema.

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

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

Gives an explicit positive condition ('Only for jobs already shortlisted by title, description and skills, when the user needs more to decide') and an explicit exclusion ('never for every job found'). The routing rule between find_jobs and get_job_details is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds genuinely new context: no hourly quota (rate-limit behavior not in annotations) and a once-per-session caching rule. It stops short of describing what the returned skill payload looks like or its size, but the safety and cost profile is well covered.

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

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

Three short sentences, front-loaded with the core purpose, then discovery pointer, then timing. The parenthetical name list is the only length and it earns its place by supplying valid values.

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

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

For a one-parameter read tool with no output schema, the description covers what it returns at a high level ('step-by-step instructions'), where to find names, and when to call it. A brief note on how large or how structured the returned skill content is would close the remaining gap.

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

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

Schema coverage is 100% and the single parameter is fully self-documented, so the baseline is 3. The description exceeds that by enumerating the valid skill names (agent, feed-tuner, filter-writing, job-scout, ratings, telegram-setup), which the schema does not provide and which functions as an effective value guide.

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

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

States a specific verb and resource ('Load a skill') and immediately defines what a skill is ('step-by-step instructions for one kind of task'). It also distinguishes itself from get_agent_context by pointing there for the index of names, so an agent can tell the two apart without opening either schema.

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

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

Gives explicit timing ('Load the skill before you act on that task, once per session') and routes discovery to the alternative tool ('Names and when to use each are in the skills index of get_agent_context'). The relationship between lookup-by-index and load-by-name is unambiguous.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety behavior is covered. The description adds useful return-content context by listing quotas, next find_jobs eligibility, feed counts, and alert-state limits, though it does not describe response structure or quota-reset semantics.

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?

It is a single efficient sentence with no filler. The comma-separated list is compact and front-loads the main quota information, though the telegraphed style is slightly less readable than a full 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 zero-parameter, read-only usage endpoint with no output schema, the description covers the key returned values an agent would need. It could say more about response shape or quota reset timing, but it is sufficient for correct 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?

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for a no-parameter tool is 4, and nothing in the description creates ambiguity about inputs.

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 specifically names the returned information: remaining hourly/daily quotas, next allowed find_jobs time, feed counts, and limits with alert status. It is clearly a usage/quota inspection tool, though the telegraphic noun-phrase style lacks a direct verb and does not explicitly contrast with sibling tools.

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

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

The phrase 'when the next find_jobs is allowed' implies the tool is useful before calling find_jobs, but it never states when to use this tool or when to prefer an alternative. Usage is inferable but not explicitly guided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the 'Read-only' phrasing is largely redundant. However, 'no hourly quota' is genuinely new behavioral information not present in the annotations, telling the agent this call is cheap and safe to repeat.

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

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

Two tight sentences: the first defines output, the second tells the agent how to use it. The most actionable guidance (ID usage) is front-loaded after the purpose statement, with zero 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?

No input params and no output schema, but the description names the returned fields and their intended use, which is all an agent needs for a static reference lookup. Nothing required to invoke or consume the result 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?

Zero parameters, so per the rubric the baseline is 4. The description goes slightly beyond by explaining how the returned upwork_id maps into other tools' filter parameters, though it adds nothing about call syntax because there is none.

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

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

States a specific verb (List) and resource (Upwork job categories and their subcategories) and names the returned fields (upwork_id, name). An agent can distinguish this lookup tool from siblings like find_jobs or get_job_details without opening any schema.

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

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

Gives concrete downstream usage: 'Use the upwork_id values in filters as base.category2_uid / base.subcategory2_uid', which tells the agent when this lookup is needed before filtering. It stops short of naming alternatives or exclusions, so it does not reach a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with "Read-only." It adds useful operational context that is not in annotations: "no hourly quota," plus the returned feed attributes and limits.

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

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

The description is front-loaded with the action and result fields, followed by a clear usage trigger and a short operational note. The field list is dense but purposeful, with no filler.

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

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

With no output schema, the description appropriately enumerates the key returned fields, including id, name, alerts, paused, filters, summary, ai_filter, agent_notes, and limits. Combined with annotations and the zero-parameter schema, an agent has enough information to call 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 tool takes zero parameters, so there is no parameter semantics gap; baseline 4 applies. The description does not need to explain inputs beyond the empty schema.

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

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

States a specific verb and resource ("List all the user's feeds") and enumerates the returned fields, making the tool's scope precise. It also distinguishes itself from nearby tools by naming find_jobs and general feed changes as follow-up consumers.

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

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

Explicitly says when to call it: to obtain a feed_id for find_jobs or any feed change. It does not enumerate when not to use it or name every alternative, but the intended usage context is clear.

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

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

Beyond annotations, it discloses user-visible side effects in Telegram, presence of an Undo button, that findings are not shown to users, that the server sets the next check, and a storage-change rate limit. These are exactly the behavioral details an agent needs before invoking a write tool.

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

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

The description is compact and front-loads the core purpose, with each detail carrying useful meaning. It is somewhat run-on and could be structured more cleanly, but it avoids wasted text.

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

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

For a write tool with no output schema and partial parameter descriptions, it covers purpose, key field semantics, user-visible effects, and rate limits well. It does not describe what the call returns or edge cases like duplicate run logging, leaving minor gaps.

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

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

Schema coverage is only 33%, but the description meaningfully explains findings, change, reason, and open_question semantics, including user visibility and one-sentence formatting. It relies on the schema for run_id and feed_id, and does not fully clarify required reason vs optional change.

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 endpoint action: ending/logging a tuner run for one feed, including no-change runs. It is clearly distinct from tuner_checkin by timing, though it does not explicitly name that sibling.

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

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

It clearly says to use this at the end of a tuner run and even when nothing changed, which is important usage context. It lacks explicit exclusions or a direct comparison to tuner_checkin, so it stops short of full routing guidance.

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

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

Annotations declare readOnlyHint=true, and the description reinforces this with 'Read-only' plus a concrete rate limit ('30 calls per hour') that annotations do not cover. It stops short of describing failure behavior for malformed or non-search URLs, but adds real operational context beyond the structured fields.

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

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

Three short sentences, front-loaded with the transformation, then usage, then routing, then constraints. No waste.

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

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

For a single-param, read-only converter with no output schema, the description supplies input format, routing guidance, and rate limits. A brief note on what the returned filters look like or error handling would close the remaining gap.

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

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

Schema coverage is 0% and the schema only gives length bounds, so the description carries the burden; it usefully characterizes the input as an 'upwork.com/nx/search/jobs/?...' link, which tells the agent the expected format. It still doesn't state what constitutes an invalid or unsupported URL, so it is not fully compensating.

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 (convert) and resource (Upwork job search link → flconsole filters) with the exact URL shape named. An agent can distinguish it from parsing tools like get_job_details or find_locations without opening the schema.

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

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

Explicitly states when to use it ('when the user already has a search on Upwork') and names three concrete downstream alternatives (preview_filters, find_jobs, create_feed). Nothing is left to inference.

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

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

Annotations already establish it as a read-only, closed-world operation, and the description layers on what annotations cannot express: a hard quota of 10 calls per hour, the exact response fields and their arithmetic (per_day_avg = matched_count / (window_hours/24)), and the caveat that the first day and today are partial and should not be compared to full days.

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?

Purpose is front-loaded, followed by response semantics, user-facing guidance, and the rate limit. It is dense but nearly every clause carries information; the 'tell the user the volume as N jobs in 7 days' sentence is presentation guidance that borders on instruction creep but still serves the preview workflow.

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

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

For a read-only preview tool with no output schema, the description fully specifies the return shape, the units, the ordering, and the partial-day caveat, plus the throughput limit. Nothing an agent needs in order to call it and interpret the result is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining how window_hours changes the derived math and why partial-day flags appear when the window starts mid-day. The nested filters object itself is fully documented in the schema, so no extra compensation is needed there.

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 operation (volume check / count of matched jobs) on a specific resource (feed filters) and positions it relative to siblings find_jobs and create_feed in the first sentence. An agent can distinguish it from find_jobs without opening either schema.

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

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

Explicitly says to run it 'before find_jobs or create_feed', which supplies ordering and context. It adds a rate-limit-derived hint (change several filters between calls), though it does not state exclusions such as when a preview is unnecessary or what to do if volume is zero.

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 say readOnly=false, destructive=false, openWorld=false; the description adds substantially more — re-rating replaces the earlier rating, and it counts as a storage change with a 30/hour budget. That mutation and rate-limit context is exactly what an agent needs and is not in 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?

Front-loaded with the verb and resource, and nearly every clause carries a constraint or disambiguation that earns its place. It is one dense run-on block though, so the parameter guidance would be easier to scan if separated from the usage rules.

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

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

For a mutation tool with no output schema, it covers everything: what gets stored, replacement behavior, rate limits, provenance of feed_id and job, and the conditional requirement on reason. Nothing an agent needs in order to call it correctly is missing.

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

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

Adds real meaning beyond the 80%-covered schema: where feed_id must come from (matched_feeds in find_jobs or the alert's feed), that job is the upwork_id, the semantics of each reason enum value (skill/budget/client/other), and that note should be the user's own words. The enum meanings appear nowhere 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?

States a specific verb and resource — recording the user's own thumbs up/down on one job — and immediately names the equivalent UI affordance (the buttons under a Telegram alert) plus what consumes the signal (offer/feed tuner). This clearly separates it from siblings like find_jobs, get_job_details, and set_feed_tuner.

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

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

Gives explicit when-to-use conditions (only when the user stated their opinion in their own words), explicit when-not (never from the agent's own judgement — route that to agent_notes; never in bulk), and a concrete exclusion (jobs from find_jobs with ad hoc filters have no feed and must not be rated).

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: discloses a 6000-character budget, a 30-storage-changes-per-hour rate limit, the PII/secret prohibition, and the expectation to tell the user what was saved. Annotations only cover mutation/openWorld flags, so this extra context is genuinely additive rather than redundant.

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

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

Front-loads the purpose and payoff, then compresses mode semantics, limits, content policy, and user-facing behavior into short clauses with zero filler. Every sentence carries an instruction the agent needs.

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

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

For a two-parameter write tool with no output schema, the description covers limits, rate limiting, mode semantics, acceptable content, and even the post-call user interaction. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning: 'append' adds a new point versus 'replace' rewriting and being the tool for condensing. It also clarifies the 6000-character total against the schema's 20000 maxLength, removing an ambiguity the schema alone would leave.

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

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

States a specific verb and resource ('Save your personal instructions about this user on the server') plus the payoff ('so any agent they start later continues with the same context'), and enumerates what belongs in it (preferences, rates, red flags, proposal style). An agent can distinguish this from get_agent_context or save_setup without opening any schema.

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

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

Gives clear operational guidance: append adds a point, replace rewrites the whole text and is the choice for condensing, plus content rules (keep short and current, no secrets or third-party personal data). It does not explicitly name the read-side sibling (get_agent_context) or state when not to save, which keeps it from a 5.

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

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

Annotations only declare the tool is not read-only and not destructive; the description goes well beyond by disclosing quota ceilings (5 alerted feeds, 5 private feeds), the exact failure mode 'feed_limit_reached', ai_filter-mediated delivery, and the Telegram side effect of notifying the user.

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

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

Front-loaded purpose, then parallel 'On:'/'Off:' branches, then the confirmation rule. Dense but every clause carries operational information (limits, failure name, filtering, notification) with no filler.

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

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

No output schema exists, and the description compensates by naming the error condition the caller may receive; quota, filtering behavior, confirmation requirement, and side effects are all covered for a 3-parameter mutation.

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 already documents all three parameters, so a 3 baseline applies; the description adds genuine value by explaining the downstream consequence of each `on` value and the conversational precondition behind `user_confirmed`.

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

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

States a specific verb and resource ('Turn Telegram notifications for a feed on/off') and immediately clarifies what each state means, including that turning alerts off leaves the feed intact — which separates it from delete_feed and set_feed_paused without naming them.

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

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

Gives explicit conditions for each parameter value (on: true sends every new matching job; on: false keeps the feed private), states the prerequisite slot limits, and adds a hard procedural rule ('Ask the user first, then pass user_confirmed: true').

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 (which only mark this as a non-read-only, non-destructive, closed-world write), the description discloses the operational consequences: no Telegram alerts, find_jobs returns feed_paused, and resuming will only deliver new jobs from that point forward rather than backfilling. It also states the human-confirmation policy, which is critical context for an agent.

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

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

Three short sentences, front-loaded with the action and direction, followed by consequences and then the confirmation rule. Every sentence carries decision-relevant information with no filler.

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

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

For a three-parameter state-changing tool with no output schema, the description covers the action, side effects, downstream effects on other tools, and the human-confirmation requirement. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful guidance on user_confirmed as an operational policy (ask the user first; never assume) rather than just restating the field. The paused parameter's semantics are repeated from the schema, which is minor redundancy.

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 precise verb pair (pause/resume) and names the resource (a feed), including the exact parameter values that select each direction. It also distinguishes this tool's effect from siblings like set_feed_alerts and delete_feed by explaining that a paused feed receives no alerts and that find_jobs reports feed_paused.

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 a clear conditional prerequisite: if the feed has alerts on, ask the user first and pass user_confirmed: true. It does not, however, contrast this with alternatives such as deleting or updating a feed, so the choice between siblings is left implicit.

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 important behavioral traits: user confirmation is required for enabling, disabling requires no confirmation, the user is notified via Telegram, and the action counts as a feed change. It does not explain effects on existing tuner runs or how changes can be reverted.

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 short and front-loaded, with the on/off conditions stated clearly. It is slightly dense but contains no redundant 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 mutation tool with no output schema and a nested parameter, the description covers the key prerequisites, side effects, and consent model. It leaves some gaps around how the tuner interacts with related feed settings, but the core information needed to call it correctly 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?

Schema coverage is 75%, but the description adds conditional meaning not expressed in the schema: target_band is required when on is true, and user_confirmed represents explicit consent in the current conversation. This is meaningful semantic guidance beyond the field 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 states a specific verb and resource: turning the feed tuner on or off for a feed, with Telegram alerts. It is clear enough to distinguish from broad siblings like update_feed, but it does not explicitly distinguish itself from set_feed_alerts or set_feed_paused.

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 concrete when-to-use conditions for both on: true and on: false, including the confirmation requirement and target_band requirement. It does not name alternative tools or state when this tool should not be used instead of related feed-setting tools.

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

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

The description asserts 'Read-only' while annotations declare readOnlyHint=false, a direct conflict about whether the call changes state. Because the structured annotation is the authoritative signal, an agent cannot tell whether check-in itself records anything. The otherwise useful notes about server-driven pacing and no hourly quota are outweighed by this contradiction.

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

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

It is short and front-loads the run-start purpose, which is good. However the field list is a comma run-on and the phrase 'since and, when due, run_id' is grammatically broken and ambiguous about which fields are always returned versus conditional. Tightening that fragment would make the definition noticeably clearer.

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

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

There is no output schema, so the description usefully names the returned fields and the early-exit case, and it warns that the server controls pacing. The remaining gap is the contradiction about read-only behavior and the absence of any pointer to the tool that records results afterward.

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 single feed_ids parameter is documented there, including its 'Feed id from list_feeds' source and the 50-item cap. The description adds a usage nuance (only when the task prompt names them) but no format or semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description gives a specific verb-plus-resource framing: it is the entry point of a feed tuner run (the scheduled 'Run flconsole feed tuner check' task) and it returns per-feed tuner state. It also enumerates the returned fields (due, stage, target_band, notes, next_check_at, since, run_id), so an agent knows what it gets. It stops short of naming the complementary sibling (log_tuner_run) to close the loop.

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?

Clear triggers and stop conditions are stated: it belongs at the start of every tuner run, 'Nothing due → stop at once', and 'do not run extra checks'. The scope note that feed_ids applies only when the task prompt names feeds is also a usage rule. It does not explicitly route to the follow-up tool (log_tuner_run) that presumably closes a run.

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 (readOnly=false, destructive=false), the description discloses the critical replacement semantics ('filters REPLACE the saved filters entirely'), that omitted keys are kept, that Telegram notifications fire when alerts are on, and the concrete rate limits (30/hr storage edits, 20/hr feed edits). These are exactly the operational facts an agent needs and cannot infer from the schema.

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

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

The description is dense but front-loaded: verb and fields first, then the replacement hazard, then the confirmation rule, then the rate limits. Every sentence carries an operational rule, though the final rate-limit sentence is compressed enough to require careful parsing.

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 7-parameter mutation with nested filter objects, the description covers the risky behavior (replacement), confirmation policy, and cost model well. Since no output schema exists, the description does not say what an update returns or how to verify the change, which is the one remaining gap.

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

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

Schema coverage is already 86%, yet the description still adds real meaning: filters must be sent whole rather than as a patch, ai_filter with an empty string removes it, agent_notes-only edits bill as a storage change, and user_confirmed is conditional on explicit user approval. run_id and its tuner-specific constraints are left entirely to the schema.

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

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

The description opens with a specific verb and resource ('Change a feed') and enumerates the mutable fields (name, filters, ai_filter, agent_notes), which is enough to distinguish it from create_feed/delete_feed. It never explicitly names those siblings, so it stops short of a 5.

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

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

It gives concrete when-to-use rules: pass user_confirmed only after showing the user the change when alerts are on, while an alerts-off feed or agent_notes-only edit needs no confirmation. It also routes the agent to list_feeds for the current filters. No guidance on when to prefer an alternative sibling (e.g., delete_feed, set_feed_alerts) for related operations.

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