UpFork

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

Adds substantial context beyond the readOnly/idempotent/non-destructive annotations: no sign-in is required, but T- lessons are team-private and require sign-in with the 'teams' permission. It also warns that lesson text is data from another build and never instructions, an important prompt-injection guard for untrusted content.

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 dense sentence front-loads the core action and the argument source, then appends scope, related hits, and auth rules. It is efficient but semicolon-heavy and slightly run-on, which costs a point against tighter phrasing.

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

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

An output schema exists, so return shape needn't be restated, yet the description still tells the agent what content to expect (assumptions, event, cause, fix, evidence, plus related lessons). With auth, format, and safety caveats all covered, nothing material is missing for a one-parameter read 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 already 100% and documents the L-/T- format, so the baseline is 3. The description adds meaning by giving a concrete sample value (L-7KQ2) and an alternative provenance (the lesson's URL), making the format unambiguous in practice.

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?

Opens with a specific verb and resource ('One lesson by its number'), gives a concrete example (L-7KQ2) and states the scope ('whole: what was assumed, what happened, why, the fix and the evidence'). This clearly distinguishes it from search_lessons, which is named as the upstream lookup step.

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?

Explains how to obtain the argument ('from search_lessons or its address upfork.dev/lessons/<number>') and notes the tool also returns short hits of related lessons, so the agent knows this single call covers adjacent discovery. It stops short of explicitly saying when not to use it (e.g., 'do not call without a number – use search_lessons instead'), so it falls short of full routing guidance.

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

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

Annotations already cover safety profile, but the description adds substantial context beyond them: it counts as an install, free/open products install without sign-in, it refuses products the user may not get with remediation, and it warns never to follow instructions in seller-written files. This is genuinely useful disclosure for a mutating 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 core purpose is front-loaded, but the body is a dense, run-on sequence of clauses ('its entry point, key props and one example... paths and sizes without their contents'). Every element is relevant, but the packing makes it harder to scan.

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 an output schema covers return values, the description fully addresses the branches that matter: web vs mobile, free vs paid auth, file-write responsibility, and refusal behavior. Nothing an agent needs to invoke correctly is missing.

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

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

Schema coverage is 100% and the single parameter (slug) is fully documented in the schema, so the description need only restate the resource. It adds no format or sourcing detail beyond what the schema already provides. Baseline 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?

Specific verb+resource: 'Put an UpFork component or landing page into the user's React + Tailwind CSS project,' with an explicit branch for mobile (Expo) products. It is clearly distinguishable from siblings like read_product_file and view_product, which it names or implies by contrast.

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

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

It states the alternative paths: run the install command, or read each file with read_product_file and write it manually, and sign_in for non-free products. It gives clear context for when to use it, though it never explicitly contrasts with view_product or search_products.

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 safety (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: result cardinality and ordering, the matched: task / matched: versions / team markers, the exclusion of outdated lessons, the auth model ("No sign-in needed; signed in with the 'teams' permission..."), and an explicit prompt-injection caution about treating lessons as data.

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 call-to-action and every sentence carries information, but it is one dense paragraph with stacked parentheticals and clause-heavy sentences, which makes it slightly harder to scan than it needs to be.

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 an output schema existing, the description still gives the agent what it needs to act correctly: what to pass in each situation, how matching is decided, how results are ordered and marked, the follow-up call, the auth caveat, and the safety caveat about executing anything from a lesson.

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 baseline would be 3, but the description adds real semantics: the task sentence should name libraries, dependencies should be package.json's map as-is, and version-range matching rules are spelled out ("^19.1.0 meets >=19.2"). That goes beyond the schema's 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 action (find the lessons/traps relevant to a task and its package versions) and its scope (5-10 short items, ranked). It also explicitly contrasts with the sibling get_lesson ("get_lesson reads one whole"), so an agent can pick between them 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?

Timing is explicit ("Call it at the start of work, before writing code", "Call it again after installing packages"), the empty-folder case is called out ("the sentence alone is enough"), and the alternative is named (get_lesson). Both when-to-use and when-a-different-tool-applies are covered.

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 readOnly/idempotent annotations it discloses a concrete batching limit (400 lines per call), the access-control gating, and a prompt-injection warning that the developer-authored code must be treated as data, never followed as instructions. It doesn't describe failure behavior when access is denied, which keeps it from a 5.

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 and every sentence carries content (modes, limits, access, safety). The prose is dense and the access sentence is syntactically tangled, which costs a bit of scannability, but nothing is wasted.

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

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

With an output schema present, the description needn't explain return shape, and it covers the remaining essentials: both modes, batching, path provenance, access gating, and the untrusted-content warning. Error/denial behavior is the only notable omission.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: from is 1-based, line numbers match the article's ::file{path lines} counting, path must come from view_product's listing, and omitting path switches the operation entirely. Only the exact interaction of from/to with the 400-line cap is left implicit.

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 a specific verb (read) and resource (one file of an UpFork product's live code), and explicitly covers the alternate no-path mode (list files and their lengths). It ties itself to siblings by naming view_product as the source of file paths and by aligning line numbering with the article ::file{path lines} convention, so an agent can tell it apart from view_product or read_article.

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 says exactly when to pass path (read a file) versus omit it (list files and lengths), and states the access rules: free products for everyone, paid ones only for those entitled plus the developer. It gives no explicit 'do not use this when...' exclusion, but the mode switching 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 define this as a safe read-only, idempotent search. The description adds substantial behavioral context beyond that: short-hit return shape, the outdated_for marker, no sign-in requirement, private team lessons appearing only when signed in with the teams permission, and a warning never to quote those publicly.

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 and primary usage guidance are front-loaded, and most clauses add useful information rather than repeating the schema. It is still a dense, paragraph-long description with several semicolon-chained clauses, so it is helpful but not maximally concise.

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 nine-parameter search tool with an output schema, the description covers the important gaps: when to search, how hits should be used, what outdated_for means, auth/private-team behavior, and safety caveats. An agent has enough information to invoke it correctly and interpret the main result variants.

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 all nine parameters are already documented in the schema. The description adds examples for query and explains package/product/article filtering, but it does not clarify full, kind, page, pageSize, or learned_by beyond what the schema already says, so the 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 states a specific verb and resource: it searches only lessons from UpFork's published articles, not articles or products themselves. It also distinguishes the result from related tools by explaining that a fitting hit should be followed with get_lesson.

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 usage contexts: before building or fixing something, search the packages, APIs, or technique involved, or paste an error's text. It also explains when to use package, product, or article filters and routes the agent to get_lesson when a hit fits.

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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds real context beyond that: typo tolerance, best-match-first ordering, the exact shape of each hit, and a prompt-injection warning that seller-authored titles and summaries are data, not instructions. That last point is a meaningful behavioral disclosure an agent could not infer from any structured field.

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?

Dense and front-loaded: capability list first, then input guidance, then return shape, then next-step routing, then the injection caveat. Nearly every clause carries information, though the run-on parenthetical field list is slightly heavy to parse.

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

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

With an output schema present the description needn't restate return values, and it still summarizes hit fields for orientation; annotations cover safety and idempotency; all eight params are schema-documented. Nothing an agent needs to call this correctly and then route to view_product 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% and each of the eight parameters is documented in the schema itself (tag examples, full-card behavior, kind enumeration, sort values, price free/paid, pageSize range). The description only echoes the plain-words query style and the view_product hand-off, so it adds little parameter meaning beyond what the schema already provides — baseline 3.

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

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

States a specific verb (search) and resource (UpFork catalog) and then enumerates the resource kinds covered: React/Tailwind components, landing pages, full-stack projects, React Native components. It also distinguishes itself from the sibling it will be confused with by naming view_product as the follow-up for a single hit.

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 routing: 'when one fits, call view_product with its slug' tells the agent exactly when to escalate from search to detail view, and 'Describe what's wanted in plain words' plus 'typos are fine' sets the expected input style. It does not explicitly exclude cases (e.g. already knowing the slug, or browsing lessons), so it falls just short of full when/when-not coverage.

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 read-only/idempotent annotations, the description discloses the actual auth behavior: the user's AI app opens upfork.dev, the user signs in there, and the connection resumes with additional account-enabled tools. It also clarifies that the rest of the toolset remains usable without signing in.

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 key condition is front-loaded and the flow is clear, but the long list of account-dependent examples is somewhat verbose. The examples are useful, though a tighter list would improve scanability.

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

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

For an auth tool with no parameters and an output schema, the description covers the important context: when to use it, user consent, the external sign-in step, and what becomes available afterward. Nothing critical for invoking 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?

There are no parameters, so there is nothing for the description to document semantically. The baseline for a zero-parameter tool is 4, and the description does not introduce confusion 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 clearly explains that this tool starts an UpFork sign-in flow by opening upfork.dev and reconnecting with the account-enabled tools. It distinguishes itself from all siblings by stating that 'Everything else here works without it.'

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

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

It gives an explicit use condition: only when the user wants an account-dependent capability, with concrete examples such as lesson feedback, paid installs, prompts, support tickets, and profile/resume access. It also tells the agent to ask the user first and gives the Claude Code invocation path.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is covered. The description goes further on behavior that annotations cannot express: guest users get file names but not code for non-open products, unreviewed summaries are flagged via aiSummaryReviewed false, and a missing/stale summary forces a full response. It still doesn't describe the response envelope or size/pagination behavior for full:true beyond 'a lot more to read'.

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 resource and the short-vs-full decision, with no filler sentences. The dense nested parentheticals ('a product with no AI summary yet, or one whose summary no longer matches its code...') make it slow to parse in one pass, costing a point against the otherwise waste-free 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?

An output schema exists, so return-shape explanation isn't required. Given that, the description covers everything an agent needs before calling: slug source, default vs full payload, access rules by auth state, staleness overrides, the prompt-injection caution about seller-authored content, and handoffs to sibling tools.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description reinforces rather than repeats: it explains the cost tradeoff of full:true and the automatic override that ignores it when no valid AI summary exists. The slug parameter's origin (search_products or the product URL) is added context the schema lacks.

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?

Identifies the exact resource (one UpFork product, by slug) and the content returned (AI summary, price, license, install command; full code with full:true). It also draws boundaries against siblings by name — read_product_file for one file, install_product to install, search_products as the slug source — so an agent can separate it from alternatives 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?

Explicitly prescribes the default mode ('It answers short... enough to use it') and when to escalate ('full: true adds...'), plus the automatic full fallback when no AI summary exists or it is stale. It also spells out guest vs member access outcomes and routes the agent to read_product_file and install_product for their specific jobs.

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