1lev1

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

Despite annotations covering the safety profile (destructiveHint=true, non-idempotent, closed-world), the description adds real behavioral context: PROFILE entries persist immediately with resources only added, WISH drafts stay drafts unless published on the site, supplier-answered rows are protected, and RIKMA yields a reviewUrl rather than being created. It omits concurrency behavior for expectedVersion and any error/conflict semantics, keeping it short of 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?

It is a single dense paragraph with the core action front-loaded, but the nested parentheticals and domain jargon ('what they set aside leaves it') make it harder to parse than necessary, and some clauses do not clearly map to an agent action.

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 mutation with no output schema and fully undocumented parameters, the description covers entity-type outcomes but says nothing about return values, error handling, or what expectedVersion guards against. It is adequate on the 'what happens' axis and thin on the 'how to call it correctly' axis.

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 description never explains sessionId or expectedVersion. The URLs mentioned (siteUrl, reviewUrl) are not parameters of this tool, so the description contributes nothing to parameter meaning even though both required parameters are opaque.

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 verb and resource ('Save a list') and then layers in entity-specific behavior for PROFILE, WISH, and RIKMA, which is more than a bare tautology. However, it never says the list is the assistant's staged items or connects to the start/revise/apply workflow implied by siblings like startAssistantTool and reviseAssistantTool, so the agent must infer the tool's role in the session lifecycle.

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

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

There is a partial when-not clause ('A RIKMA is never created here', supplier-answered rows are never changed here), but no positive statement of when this tool should be preferred over siblings such as setAssistantItemsTool or undoAssistantTool. The agent gets no trigger condition for invoking it.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds substantial context beyond them: it is a soft-delete, the product stays reachable at /gift/[id] for historical orders but disappears from /gift and the storefront catalog, it is never a hard delete, and the rikma path returns a moach link rather than archiving.

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 core purpose and keeps each sentence functional, but is dense with internal jargon (rikma, moach, restime, Matanot) and packs the sibling-routing, location behavior, and unarchive note into a compact block that a first-time agent must parse carefully.

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 soft-delete tool with no output schema, the description covers ownership prerequisites, the consent-flow divergence, what persists vs vanishes, irreversibility of the delete, and where unarchiving happens – everything needed 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?

Schema coverage is 100%, so the schema already documents all three parameters, including the archived=true/false semantics and the moach-link return for false. The description largely echoes that behavior without adding syntax or constraints the schema lacks, so the 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?

States a specific verb (archive/soft-delete) and resource (a personal product with origin=personal you own), and immediately distinguishes it from updateRikmaProductTool, getRikmaProductTool, and createRikmaProductTool by scoping it to personal products rather than the rikma flow.

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 use it (personal products you own) and when not (rikma products, which route through the proposeObjectArchive consent flow and return a moach link instead), and further tells the agent that unarchiving happens in the moach, not here.

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=false and non-idempotent/non-destructive, so safety is covered. The description adds genuine behavioral context by clarifying this only links pre-existing objects and requires a prior create step, which is not derivable from 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?

Two sentences plus a docs link; the core action is front-loaded and the create-first caveat is placed immediately after. The 'so what the rikma is pursuing and what it is actually doing about it stay connected' clause is rhetorical padding, but overall it is tight.

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 five-parameter mutation with no output schema but full annotation coverage, the description supplies the prerequisite workflow and object scope an agent needs. It omits expected behavior on repeated attaches (relevant given idempotentHint=false), which keeps it short of full completeness.

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 five parameters are already documented in the schema. The description loosely maps its prose to the entityType enum values but adds no format, id-sourcing, or naming detail beyond what the schema 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?

States a concrete verb (attach) and resource (an existing object to a process), and enumerates the object kinds it accepts (open mission, open resource, mission in progress, voted-on mission/resource). This lets an agent separate it from creation-oriented siblings, though the jargon ('rikma') adds noise rather than precision.

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 gives the precondition ('It does not create the object: create it first') and names the alternative paths (prepareMissionTool, createTaskTool, or the URL the tool returns). Clear context for use; no explicit when-not condition, but the create-vs-attach split covers the main ambiguity.

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: it discloses that rows are saved verbatim with no second model rewriting them, that nothing is actually created (only proposals the user approves at the returned reviewUrl), that invalid rows come back in `rejected`, and that `error.retryable` signals whether a retry helps. The idempotentHint=false annotation is given real meaning by the 'proposal' framing.

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 defining constraint and the sibling routing, and every sentence carries information. It is dense but no sentence is wasted; slightly long for a single paragraph, though appropriate given the schema 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?

With no output schema, the description still covers the return surface (reviewUrl, `rejected`, `error.retryable`), the save semantics, and the alternative tool. An agent has everything needed to call this correctly and interpret the result.

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

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

Schema description coverage is 100% and the field descriptions are already detailed, so the baseline is 3. The description reinforces that every row needs both name and descrip and that violating this yields `rejected` rows, but it adds little else beyond what the schema already documents.

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

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

States a specific verb and resource ('Create a planning board') plus the key qualifier 'from rows YOU already structured,' which immediately separates it from the AI-generating sibling planProjectWorkTool.

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 names the condition that selects this tool ('when the conversation already holds the breakdown') and the alternative with its own condition ('Use planProjectWorkTool instead when the user only has a loose idea in free text'). Also states the projectId prerequisite.

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 give readOnlyHint=true and idempotentHint=true, but the description adds crucial context the annotations cannot: the tool returns a prepared link, nothing is created until the user approves, and the returned `url` must be presented verbatim. The nonprofit clarification is genuine behavioral context about how `profit: never` is interpreted by the system. This exceeds what structured fields 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?

Front-loaded with the core action and the 'nothing is created yet' caveat, which is good. However, the middle sentence about public support pages is lengthy and feels like promotional framing rather than operational guidance; it could be trimmed. The instruction to pass the URL verbatim is valuable, but the sentence order buries it after the nonprofit tangent.

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 no output schema and 8 parameters, the description does the heavy lifting: it defines the return value (a link), explains the lifecycle (prepared → user approves → created), warns against URL tampering, and disambiguates the nonprofit case. This is complete enough for an agent to invoke correctly without opening 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?

Schema description coverage is 100%, so the schema already documents all 8 parameters. The description reinforces the `profit` enum semantics ('never' means selling is not the goal) and explains the public support page concept — which is parameter-adjacent context a first-time caller might miss. It doesn't add syntax or format detail beyond schema, keeping it at 4.

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 (prepare a form, return a pre-filled link) plus the key semantic correction that nothing is actually created yet. The term 'rikma' is defined inline and the distinction from any real creation is immediate. An agent can tell this apart from prepareSignup / prepareMission / startProcessTool 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?

Clearly signals when to use: when a user wants to prepare a Partnership form. It also clarifies the nonprofit case ('A public-benefit or nonprofit initiative is a normal Partnership'). But it doesn't explicitly name a sibling alternative or state when NOT to use it (e.g. when the Partnership already exists — that's getProjectDetailsTool territory).

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 non-read-only, non-destructive, non-idempotent. The description adds real behavioral detail beyond that: per-item isolation ('one failure never stops the rest'), the results[i] shape with productId or failure reason, and partial-success marking when extras fail. It also discloses the members-only authorization requirement.

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 capability and limit, then failure semantics, then auth, then docs link. Four tight sentences with no filler; the field enumeration is the only mildly redundant part.

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 2-parameter but deeply nested mutation with no output schema, the description covers return shape (results[i]), partial-failure semantics, the item cap, and auth. Minor gaps remain: no mention of whether the whole batch is rejected on malformed input versus per-item, and no rate/throughput expectations.

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 50%, but the nested item schema is unusually self-documenting, with every property described inline. The description only re-lists field names (name, description, price, stock, pictures, categories, options, variants) without adding format or constraint meaning, so it neither compensates nor detracts.

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 and hard scope: 'Create up to 30 products in one rikma in one call'. It also anchors itself to the sibling single-item tool ('same fields as createRikmaProduct'), so an agent can distinguish batch from single creation 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?

Clear context for use (bulk creation, up to 30 items, membership required) and an implicit routing rule via the createRikmaProduct reference. It does not explicitly say when to prefer the single-item tool or what to do if more than 30 items are needed, so no full when-not 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 declare non-read-only, non-idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds substantial behavior beyond that: the three hosting modes and their branching, the side effect of creating a brand-new rikma when newRikmaName is supplied, the membership requirement, and what the call returns (new Matanot id and where it lives). It does not discuss validation failure behavior or partial-failure on the newRikmaName path, 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?

Front-loaded with the three hosting modes, then the storefront field list, then the alternative-tool routing, then return value and docs link — a sensible hierarchy. It is dense but not padded; the only slight waste is re-listing schema fields (name, description, price, stock) that the schema already documents.

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 14-parameter mutation tool with nested objects and no output schema, the description covers the hosting-mode decision tree, permissions, the state-changing side effect of rikma creation, and the return value. An agent has enough to invoke it correctly on the first attempt.

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 cross-parameter meaning the schema cannot express: projectId alone vs omitted vs newRikmaName are mutually exclusive hosting modes with different ownership outcomes, which is the single most error-prone decision in this call. It also clarifies quant=-1 as unlimited and the quant×price interpretation behind kindOf.

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

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

States a specific verb and resource — 'Create a fixed-price product (Matanot) for the rikma' — and immediately differentiates itself from the sibling createComplexMatanot (complex recipe/BOM) and implicitly from createRikmaProductsBatchTool. An agent knows exactly what this produces without consulting any other tool.

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 routing: use this for the simple shippable shelf item, use createComplexMatanot for BOM/margin/estimated-price recipes. It also names the prerequisite helper tools (listRikmaCategories, upsertProductVariants) and the permission condition ('Members or personal owner'), leaving little 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?

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), the description discloses the approval workflow for acts assigned to others ('nobody is bound until they accept'), role-holder notification behaviour, and the caller membership prerequisite. These are non-obvious behavioural details not derivable from 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?

Front-loaded with purpose then bulleted decision shapes, which is well structured. The framing sentence ('Whenever the user wants something new to happen...') and the trailing docs link are mild padding, but nothing is genuinely wasteful for a 10-parameter tool with multiple modes.

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, a 10-parameter mutation tool is fully covered: prerequisite membership, required project ID, the two assignment modes, approval semantics, and a docs link. An agent has everything needed to choose and invoke it.

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 relational meaning the schema only partly encodes: which parameter set belongs to which mode (missionId paired with assignedUserId; tafkidims as the no-assignee path), and how getMemberMissionsTool / getProjectMembersTool resolve the IDs. It stops short of format details 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?

States a specific verb and resource - create a task in a project - and immediately scopes what a task is ('the way a member gets something new done'). It explicitly contrasts itself with prepareMissionTool, so an agent can route 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?

Gives three explicit decision branches (existing mission -> create act linked to it; nobody does this kind of work -> use prepareMissionTool instead; no specific person -> create unassigned with tafkidims). When-not-to-use is stated as directly as when-to-use, with the named alternative tool.

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

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

Beyond the annotations (which only say non-readOnly, non-destructive, non-idempotent), the description discloses that the link is short-lived with a 60-minute validity, accepted formats (JPG/PNG/WebP), a default of 10 and cap of 20 files, member-only access, and that it performs no attachment. These are exactly the operational constraints an agent needs and none of them are in 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?

It is front-loaded with the purpose and the workflow ordering, and every clause carries information (format limits, expiry, member restriction, non-attachment caveat). It is a dense single paragraph rather than clearly segmented bullets, which slightly hurts scanability for an agent parsing multiple constraints.

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 tool with no output schema, the description covers the full lifecycle: creating the link, handing the URL to the user, retrieving upload ids via getUploadSessionTool, and finalizing with setProductImages. Constraints, validity window, and access requirements are all 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 100%, so the baseline is 3, but the description reinforces the default and hard cap on maxFiles and clarifies that the link's scope is the project with a member requirement. It adds little beyond the schema definitions of productId and projectId, so it falls short of a 5.

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 a short-lived link where the user uploads product pictures') and immediately distinguishes itself from media-reading tools by noting 'you do not get the bytes of attachments'. It is also clearly separable from uploadMediaFromUrlTool and setProductImagesTool, which it names.

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 triggering condition ('when the user has pictures you cannot read'), the follow-up workflow ('call getUploadSession with the token to get the upload ids, then setProductImages'), and the excluded case ('the link only adds pictures to the media library — it attaches nothing'). An agent has no ambiguity about when to pick this tool versus the image-setting 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 destructiveHint=false and readOnlyHint=false, so the agent knows this is a non-destructive mutation. The description adds genuinely new behavioral context: it is a private, per-user filter ('a filter for them only - nobody is told no'), which is not conveyed by any annotation.

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 short sentences front-load the effect, and the privacy clarification follows immediately. The trailing docs URL is useful and cheap. The phrasing is slightly informal but not padded.

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

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

For a single-parameter mutation with a full annotation profile and no output schema, the description covers effect, scope, and privacy adequately. The only gap is how to obtain a valid openMissionId, which the docs link partially addresses.

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

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

There is one required parameter (openMissionId) with 0% schema description coverage. The description's reference to 'an open mission suggested to them' implicitly ties the parameter to that mission, but it adds no format, source, or retrieval guidance beyond the schema's type.

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 concretely states the effect: a suggested open mission stops being suggested to the person. It is a distinct operation from siblings like findMissionTool or listMyWishOffersTool. It stops short of using a crisp verb+resource phrasing, describing the outcome narratively instead.

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 implies the trigger condition ('the person says an open mission suggested to them is not relevant'), which gives usable context. However, it names no alternative tools or when-not-to-use guidance, so an agent must infer how this differs from related actions such as finding or applying to missions.

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 behavior, so the safety profile is covered. The description adds only the lookup-by-name behavior; it says nothing about match semantics (exact vs partial) or what happens when no mission matches.

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 short sentences, purpose front-loaded, no wasted prose. The trailing docs link is minor filler but harmless.

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

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

For a single-parameter read tool with rich annotations and a fully documented schema, the definition covers what an agent needs to invoke it. Return shape and no-match behavior are unaddressed but the annotations and simple schema make this acceptable.

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% for the single missionName parameter, so the schema does the heavy lifting. The description's 'by its name' merely restates the parameter without adding format or matching semantics.

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 (find), resource (mission), scope (for the user) and lookup key (by its name). It is distinguishable from list/get siblings at a high level, though it never names them 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?

No when-to-use guidance and no mention of alternatives such as getMissionDetailsTool, listUserMissionsTool, or getMemberMissionsTool. An agent must infer on its own whether this returns full details or just a handle.

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, idempotentHint, and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond them: results are ordered newest-first, include creation time, and are paginated with hasMore/nextOffset. It does not disclose rate limits or result cap behavior, so not 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?

Three sentences, front-loaded with the core purpose, followed by trigger conditions and pagination mechanics. Every sentence carries actionable information; nothing is redundant with the schema or annotations.

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

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

With no output schema, the description compensates by describing what comes back (projects with creation time, ordering, pagination cursor fields). All four parameters are covered by the schema, and usage triggers plus pagination are fully specified, leaving no gap an agent needs 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?

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining the pagination contract (when hasMore is true, call again with offset=nextOffset), which ties the offset parameter to a return value the schema cannot express since there is no output 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 (find) and resource (the projects/rikmot the current user belongs to), plus ordering (newest first) and returned field (creation time). It is clearly distinguishable from siblings like getProjectDetailsTool, listProjectResourcesTool, or listRikmaProcessesTool.

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 trigger conditions: when the user mentions a project by name, wants to navigate to one, or just created one. It also states the pagination follow-up rule. It does not name a specific alternative sibling to avoid, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: no note on whether timers are per-user only, no ordering, no freshness of the data, and no behavior of the includeDetails flag.

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?

One short sentence, front-loaded with the core action, followed by a documentation link. No padding beyond the boilerplate URL, though the URL is not actionable for tool selection.

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

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

For a simple read-only lookup with rich annotations and no output schema, the definition is minimally adequate. It omits any description of what the returned timer records contain and how active is defined, which an agent would need since there is no output schema to consult.

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 includeDetails parameter has a documented meaning and default, so the schema does the heavy lifting. The description adds no semantics on top, which lands at the baseline for a fully covered 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 with a scope qualifier ('currently active timers for the user'), which separates it from the sibling timerActionTool that presumably mutates timers. It does not, however, explicitly name the sibling or contrast behavior, so it falls 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?

The description gives no when-to-use or when-not-to-use guidance and never references timerActionTool, the obvious alternative for acting on timers. An agent must infer the intended context purely from the tool name.

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, and non-destructive behavior, so the safety profile is covered. The description adds useful context beyond that: it discloses the returned payload (rows, keys, status, version, recent changes) and the version-freshness motivation for calling it.

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, but the single sentence is dense and includes noise like the awkward parenthetical "(also from the site)" and an external docs URL. The core guidance survives, but the prose could be trimmed without loss.

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 describing returns and does so (rows, keys, status, version, recent changes), which is the key missing piece for a read tool. The only residual gap is the undocumented sessionId parameter and the unclear relationship to other read siblings.

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 50%: kind has an enum with a short description, while sessionId is undocumented. The description partially compensates by naming the kind values (rikma blueprint, profile, wish) and implying "latest session" semantics, but sessionId remains unexplained in both schema and description, so this sits 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?

States a specific verb and resource ("Read the person's current draft list on 1lev1") and enumerates the three kinds (rikma, profile, wish), which distinguishes it from write-oriented siblings like setAssistantItemsTool. It does not, however, clarify how it differs from getWishDetailsTool or listRikmaProcessesTool, so it falls short of full sibling differentiation.

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 gives a when-to-use condition with an alternative: "Call it before setAssistantItems when you are not sure you have the latest version." That is actionable routing guidance, though it covers only one sibling and offers no when-not 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 read-only, idempotent, non-destructive, closed-world behavior, so the description's job is narrower and it delivers extra context: a members-only authorization requirement, an explicit PII handling warning (phone/email never to be copied elsewhere), and log ordering (most recent first). It stops short of covering payload size, truncation, or not-found 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?

Front-loaded with the verb and resource, then a single dense enumeration of returned fields; the members-only gate and docs link are cleanly separated. The long em-dash parentheticals make it heavier than necessary, but each listed item carries useful selection signal.

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 by enumerating return contents and log ordering, and it flags the authorization and sensitivity constraints for this read tool. Missing only edge-case behavior (lead not found, access denied, log truncation beyond logLimit).

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 three parameters (projectId, leadId, logLimit with default 20 and max 100) are already documented. The description only indirectly touches parameters by noting the log is most-recent-first, which gives ordering context for logLimit but nothing 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?

"Open one lead of a rikma" gives a specific verb and singular resource, and the enumeration (identity/contact, request, stage, owner, next step, follow-up date, linked orders, log) tells an agent exactly what comes back. The singular framing plus the leadId schema hint clearly separates it from listRikmaLeadsTool.

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

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

Usage is implied: fetch one lead's full record when you already have its id. There is no explicit when-to-use/when-not guidance and no named alternatives (e.g. listRikmaLeadsTool to find ids, logLeadActivityTool to add entries), only a hard "Members only" gate.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds genuine workflow behavior: that output feeds a missionId into createTaskTool and that tasks require a mission-in-progress. It does not describe pagination or return shape, but that is a minor gap given 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-loads the purpose, then the workflow reason, then the alternative, in three tight sentences. The docs link is the only optional element and every sentence earns its place.

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

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

With no output schema, the description still conveys that the result is a set of missions from which a missionId is selected, which is enough to use it correctly. It stops short of naming return fields, but the workflow framing compensates well.

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, establishing a baseline of 3. The description clarifies that userId is 'the assignee (a person)', which reinforces but does not extend the schema's own description, and adds no format or constraint details.

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 a project member's in-progress missions') with the scoping qualifier 'in-progress' that narrows it meaningfully. It does not explicitly contrast with the close sibling listUserMissionsTool, so it falls short of full sibling differentiation.

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 ('call this after choosing the assignee... to pick the missionId to pass to createTaskTool') and an explicit when-not with an alternative ('If no mission in progress covers the work... prepare a mission with prepareMissionTool instead'). Both the trigger condition and the fallback sibling are named.

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, so the safety profile is fully covered. The description adds a useful note that the payload includes tasks, timeline, and status, but says nothing about error behavior for an invalid/unknown missionId or about response size.

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 front-loaded sentence with the payload contents listed immediately, followed by a documentation link. No filler, though the bare URL adds little routing value 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?

For a simple read-only single-parameter tool, the description covers what the tool returns, which partly compensates for the absent output schema. Missing only edge-case behavior (invalid ID, permissions), which is minor at this complexity.

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?

Only one parameter exists and the schema documents it fully at 100% coverage ('Mission ID to get details for'). The description adds no format, prefix, or lookup guidance beyond what the schema already provides, 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?

States a specific verb ('Get') and resource ('detailed information about a specific mission') and enumerates the content returned (tasks, timeline, current status). This distinguishes it from listUserMissionsTool and getMissionStatsTool, though it never explicitly names those siblings as alternatives.

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

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

There is no explicit when-to-use guidance or comparison against the many mission-related siblings (findMissionTool, getMissionStatsTool, getMemberMissionsTool, listUserMissionsTool). 'A specific mission' weakly implies you must already hold a mission ID, but the agent must infer this.

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, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds a partial view of what the result contains (counts by status, time spent), but does not describe aggregation scope, whether counts are per-project or global, or pagination/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?

Two compact sentences, front-loaded with the purpose and followed by a docs link. Nothing is wasted, though the trailing URL adds little for an agent that already has the schema.

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 should carry more of the return-value burden. It gestures at the return shape ('counts by status, time spent, etc.') but leaves the 'etc.' vague and never clarifies scope (global vs per-project) or result size.

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?

Only one optional parameter exists and its schema description ('Get stats for specific project only') is fully covered at 100%. The description adds nothing about projectId or its default behavior when omitted (presumably all projects), so 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?

States a specific verb and resource ('Get statistics about user missions') and names the kind of data returned (counts by status, time spent). It implicitly distinguishes itself from siblings like getMissionDetailsTool and listUserMissionsTool, but never explicitly states the difference.

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

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

There is no when-to-use guidance and no mention of alternatives such as getProjectStatsTool, getMissionDetailsTool, or listUserMissionsTool, which are the closest siblings. The agent must infer that this tool is for aggregate stats rather than listing or detail retrieval.

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 read-only/idempotent/non-destructive, and the description adds substantially more: it explains that mutations happen on the site, that sentences must be relayed verbatim without rewording figures, that silenceApproves deadlines auto-approve, and that `unavailable` sections must be reported as unread rather than empty. That is genuine behavioral 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?

It is dense and long, but front-loads the core purpose and then groups the return fields (waiting, work, whatsNew, suggestions, unavailable) with actionable instructions. Almost every clause carries information an agent needs, though the volume pushes against easy scanning.

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 carries the full burden of explaining the return payload, and it does so thoroughly for a multi-section, complex aggregation tool. An agent has enough to call it and interpret every response section 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 lang, limit, rikma, and projectId are already fully documented in the schema, setting the baseline at 3. The description only lightly maps to parameters via the 'rikma X' scenario and the language instruction, adding marginal value 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 aggregation purpose: 'what waits for the user and what is new for them' across rikmas, wishes, and deals. It is clearly distinguishable from point-lookup siblings like findUserProjectsTool, listMyWishesTool, or getMissionDetailsTool, which each cover only one slice of what this digest rolls up.

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 invocation phrasings ('what's new today', 'what is waiting for me', 'what is happening in rikma X'), which is strong when-to-use guidance. It stops short of naming a sibling alternative or stating when not to use it (e.g., single-item lookups), so it lands at 4 rather than 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond a docs URL — no note on what the response contains or how fresh/authoritative it is. Baseline credit for a safe read with no additional behavioral insight.

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 front-loaded sentence stating purpose, scope, and a docs link, with zero redundancy. Nothing could be removed 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 no output schema, the description hints at content ('goals, and features') and points to docs, which is reasonable for a trivial no-param info tool. It stops short of describing the actual return shape, but that gap is minor given the tool's simplicity and its safety annotations.

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 nothing for the description to disambiguate. Baseline of 4 applies for a no-param tool with an 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 ('Get') and resource ('general information about the 1lev1 platform, its goals, and features'), which clearly sets it apart from the mission/project/task oriented siblings. No explicit sibling differentiation is offered, but the meta/info nature makes it unambiguous.

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

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

Usage is only implied: an agent should call this when it needs platform context. There is no explicit when-to-use, no exclusions, and no reference to any alternative tool. Acceptable but minimal.

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, idempotentHint, destructiveHint=false and openWorldHint=false, but the description adds real behavioral context: the permission-scoped return ('For a rikma the user is not a member of, only the public face is returned (isMember:false)') and the cost/latency characterization ('it is cheap'). It does not describe pagination or output shape, but for a read tool with full annotation coverage this is strong added value.

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, then usage guidance, then the membership caveat, then a docs link. The long enumeration of returned fields is somewhat dense but earns its place by summarizing a return payload that has no output schema. Minimal 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?

With no output schema, the description carries the burden of describing returns and does so by listing the returned entities (members, roles, missions, resources, products). It is nearly complete; only the shape/format of those returns and any pagination behavior are unspecified, which is minor for a single-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 description coverage is 100% and the single parameter (projectId) is documented in-schema as coming from findUserProjectsTool. The description adds nothing about the parameter, so the baseline of 3 applies when structured data does the heavy lifting.

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 ('Get the facts about one rikma (project)') and enumerates the exact facts returned, immediately distinguishing it from scanProjectDirectionsTool by contrasting 'returns facts' with the latter. An agent can select it 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 explicit when-to-use guidance ('Call this before planning or writing anything in a rikma') and names the alternative tool along with the reason to prefer this one ('it is cheap and returns facts, unlike scanProjectDirectionsTool'). Covers both the condition and the exclusion.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: this is a prerequisite lookup step feeding createTaskTool, and the query param filters by name. It does not describe the shape of the returned member/role list, which is the 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?

Three sentences, front-loaded with what the tool returns, then the workflow reason, then the edge case. The docs link is placed last and costs nothing. No sentence is redundant.

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 read-only lookup with no output schema, the description covers purpose, routing and the follow-up call adequately. What is missing is any hint of the return payload (e.g. that each member/role comes back with an ID), which the agent needs to chain into createTaskTool.

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 (projectId, query) are already documented in the schema and the description need not repeat them. Its mention of 'pass their IDs as tafkidims' refers to createTaskTool's parameters rather than this tool's, so it adds no additional semantics for the two inputs here.

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

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

States a specific verb+resource ('List the people (members) and roles (tafkidim) of a project') and immediately scopes it to a distinct concern that no sibling covers. It also introduces the domain term 'tafkidim', which removes ambiguity about what 'roles' means in this system.

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 names the trigger ('resolve a task assignee ... before calling createTaskTool') and the alternative branch ('for a task with no specific person, pick the roles that fit it here and pass their IDs as tafkidims'). This is a when-to-use plus a when-to-use-differently, which is the strongest form of 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds scope context beyond the annotations: it is members-only and excludes financial data, and it clarifies the trailing-window semantics of the counts.

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 the metric list, then usage, then a docs link. The enumeration is long but justified because there is no output schema; the trailing docs URL is the only low-value element.

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 return-shape burden and does so by listing every metric plus a last-activity timestamp. Source of projectId and the days window are covered by the schema, so an agent has everything needed to call and interpret it.

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 in the schema (days default 30, projectId sourced from findUserProjectsTool). The description only alludes to 'the last N days,' adding no syntax or format detail beyond the schema, so the 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?

The description names a specific verb+resource and then enumerates the exact metrics returned (members, open missions, missions in progress, resources, decisions, timers, finished missions, hours logged), which distinguishes it from getMissionStatsTool and getProjectDetailsTool 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?

It gives an explicit use case: 'Use it to judge whether a rikma is active before planning,' and an exclusion ('no per-member financial data'). It does not name a sibling alternative (e.g. getProjectDetailsTool) for the case where narrative detail is wanted, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the return composition ('plus the holder and the note the rikma sees') and the members-only access rule, including that buyer contact is restricted. Useful context beyond structured fields, though no pagination or error behavior is disclosed.

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

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

Three tight sentences, purpose front-loaded, each sentence carrying distinct information (lookup, return shape, access rule). 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 simple 2-param read tool with full annotation coverage, the description is nearly complete: it explains what is fetched, what is returned, and the access limitation. Only minor gaps around error behavior for a missing ref remain.

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. The description adds the provenance of the ref format ('as POST /orders answered'), but the dual ref/orderId behavior is already in the schema, so this sits at the baseline for high 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?

States a specific verb (Get), resource (one order of the rikma), and lookup key (by its ref). The word 'one' plus the reference to 'the list' cleanly distinguishes it from listRikmaOrdersTool without the agent 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?

Provides a clear access precondition ('Members only') and implies single-order retrieval versus the list variant. It stops short of an explicit 'use this instead of listRikmaOrdersTool when...' routing statement, but the context 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context beyond them: membership requirement and the full breadth of the payload returned (variants, computed inventory, gallery/delivery options).

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, then the payload, then usage and docs. It reads as one long sentence and the exhaustive field enumeration is dense, but since there is no output schema that enumeration 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, the description carries the return-value burden and does so thoroughly; it also notes members-only access. Only minor gaps remain (no error/pagination or clarity on how archived rows affect the return unless includeArchived is set).

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%, including the important 'includeArchived' default-true semantics and the note that productId comes from listRikmaProducts. The description adds no parameter syntax beyond the field listing, 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?

States a specific verb+resource ('Get one product of the rikma') and then enumerates exactly what comes back: base row, gallery/delivery, option axes, variants, categories, computed inventory. This clearly separates it from listRikmaProducts, listRikmaProductVariants and updateRikmaProductTool.

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 a concrete use case ('verify a product before editing stock, pricing or variants') and an eligibility constraint ('Members only'). It does not state when NOT to use it, but the intended workflow context is explicit and actionable.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds value beyond them by disclosing the 'Members only' authorization requirement and by detailing the configuration content returned, which substitutes for the missing output 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?

Purpose and return contents are front-loaded in a single dense sentence, followed by the usage routing and a docs link. The long enumeration is heavy but justified given there is no output schema; little of it 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 no output schema, the description carries the return-value burden and does so thoroughly, while also covering auth (Members only) and disambiguation from quoteShipping. Nothing an agent needs to select and invoke this 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?

One parameter at 100% schema coverage, where the schema already documents projectId and its source (findUserProjectsTool). The description adds no format or syntax detail for the parameter, 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?

States a specific verb (Describe) and resource (how a rikma delivers what it sells), then enumerates the exact configuration facets returned: setup status, currency, handling days, zones, methods, pickup points, per-product rules. It is unmistakably distinct from quoteShippingTool and the rest of the shop/product 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?

Explicitly routes the agent: for "how much is delivery of X to <city>?" use quoteShipping instead, because it prices a real cart. That names the alternative and the condition that selects it, plus a hard constraint (Members only) that gates 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?

Annotations already declare the safe read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds useful context beyond them: the 'Members only' authorization requirement and a breakdown of what the response contains (counts, per-variant stock, waiting orders, oversold units).

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 resource and its contents are front-loaded in the first two sentences, and the prerequisite follows. There is mild filler ('so the seller knows what the shelf does not cover', 'as facts an agent can act on') that does not add actionable information, keeping 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?

With no output schema, the description carries the return-value burden and does so by enumerating the aggregate fields returned. Combined with annotations covering the safety profile and a documented 'Members only' constraint, an agent has enough to invoke it correctly; only pagination/size expectations are unaddressed.

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 (projectId, includeArchived) are already documented by the schema. The description alludes to archived counts implicitly but adds no syntax, defaults, or format detail beyond what the schema 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?

States a specific resource ('Inventory overview for a rikma') and enumerates exactly what it aggregates: active/archived/low/out-of-stock counts, per-variant stock, waiting orders, and oversold units. This differentiates it from the list-style siblings (listRikmaProductsTool, listRikmaProductVariantsTool) because it returns aggregate counts rather than item lists.

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 prerequisite ('Members only') and a real-world anchor ('what the Stock tab of sales/manage shows'), which implies when the tool is relevant. However, it never states when to prefer this over listRikmaProductsTool or its write counterpart setShopStockTool, so routing between siblings 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds only the notion that the result is a 'structured list', without saying anything about the shape, size, pagination, or caching behavior of that list.

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 front-loaded sentence naming verb, resource, and scope, followed by a documentation pointer. Nothing is redundant and nothing buries the operative 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?

For a no-parameter, read-only listing tool with no output schema, the description covers purpose and points to external docs. The only shortfall is that 'structured list' leaves the return shape unspecified, though annotations already handle the safety and side-effect questions.

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 nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level claims are made that could mislead an agent.

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 ('Get a structured list of available pages on the 1lev1.com site'), which is far more informative than the bare tool name. It does not, however, differentiate itself from the closely related sibling navigateToPageTool, so an agent cannot tell from the description alone which of the two to pick.

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?

'useful for navigation' implies a context of use, but it is a one-clause hint rather than an explicit when-to-use statement. There is no guidance on when-not to use it or how it relates to alternatives such as navigateToPageTool, searchCatalogTool, or searchContentTool.

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

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

Annotations already cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely new behavior: an authorization constraint ('Only the user who created the link can read it') and an ordering guarantee ('in the order they arrived'). Return shape and pagination limits are not mentioned, keeping it below 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?

Two dense sentences: purpose and returned fields first, then the downstream hand-off, then the auth caveat. Nothing is redundant, and the docs link is the only marginal addition.

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 parameter, no output schema, and annotation coverage already in place, the description supplies what is missing: the returned fields, ordering, authorization scope, and the natural next tool. An agent can call it and use the result without further inference.

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

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

There is a single parameter with 100% schema description coverage, so the schema already explains that the token comes from createUploadSession. The description only restates the same provenance, adding no extra meaning such as token expiry or reuse semantics; 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?

States a specific verb+resource ('List the pictures uploaded through an upload link') and anchors it to the sibling that creates the link (createUploadSession). It also enumerates the returned fields, so an agent knows exactly what it gets 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 routes the result downstream: 'Pass the uploadIds to setProductImages or createRikmaProduct', which tells the agent when this tool is the right prerequisite. It stops short of an explicit when-not-to-use case or a named alternative lister, so it is strong rather than complete.

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, so the safety profile is covered. The description adds genuinely new behavioral context: permission-dependent visibility (owner/proposer vs. public card) and the warning that proposal decisions cannot be made here but require opening a returned URL. It does not mention pagination or rate limits, keeping it at a 4.

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, followed by return contents, access scoping, and the accept/decline caveat in three efficient sentences. The trailing docs URL is minor overhead rather than filler, so it is not perfectly minimal.

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

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

For a single-parameter read-only tool with no output schema, the description does the heavy lifting by describing what is returned (missions, resources, coverage, proposals) and the visibility rules. The reference to a returned URL implies response shape without fully specifying it, leaving a small 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?

Only one parameter (wishId) with 100% schema description coverage, and the schema already explains its origin (from listMyWishes or a /concierge or /wish URL). The description adds no additional parameter meaning, 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?

States a specific verb and resource ('Get one wish (concierge request)') and enumerates exactly what it returns: needs broken into missions and resources, coverage, and proposals. This clearly separates it from siblings like listMyWishesTool (plural list) and getMissionDetailsTool (different resource).

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 when the tool applies, including the access-scoped outcomes ('Full detail for the wish owner and for anyone who proposed on it; others see only the public card of an open wish'). It also excludes an adjacent action ('Accepting or declining a proposal is never done here'), but does not name a sibling tool alternative, so it stops short of 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds behavior the annotations cannot express: result ordering ('newest first'), result granularity (one conversation per involved entity), and payload content ('with the last message'). It omits pagination behavior for the limit parameter, so it falls short of full transparency.

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

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

Front-loaded with the core action, then the scoping clause, then the usage cue and docs link; every sentence carries information. The enumeration of entity types is somewhat long but it defines the tool's granularity, so it earns its space.

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 responsibly covers what comes back (last message, newest-first ordering, one row per thread). The remaining gap is pagination/limit interaction, which an agent calling a list tool would benefit from knowing.

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%: limit already documents its default (25) and maximum, and projectId documents its meaning. The description adds no syntax or format detail beyond the schema (it doesn't even mention projectId), so the 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?

The description states a specific verb and resource ('List the conversations (forums) the caller takes part in') and pins down the scope that separates it from siblings: only threads the caller participates in, one per mission/act/decision/profit split/wish proposal. An agent can distinguish this from listMyWishesTool, listMyWishOffersTool and readConversationTool 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 gives a concrete trigger ('Use it to find the forumId of the thread a request is about'), which is a real workflow cue. It does not, however, name the alternative tools (readConversationTool, openRikmaConversationTool) or state when not to use it, so routing between the conversation siblings is only partially resolved.

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 and non-openWorld behavior, so the safety profile is covered. The description adds only the shape of the payload (status, coverage, counts), with nothing about ordering, pagination, or result limits for a list operation.

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

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

Two compact sentences that front-load what is listed and when to use it, followed by a docs link. No restatement of the title and 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 parameters, no output schema, and annotations covering the safety profile, the description supplies what an agent needs to select and call it. It stops short of describing result volume or ordering, which matters slightly for a list tool in a family of 40+ siblings.

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. The description correctly adds no parameter guidance because there is nothing to configure, and it does note the per-wish output 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?

States a specific verb and resource ('List the caller's own wishes'), and the parenthetical '(concierge requests)' plus the field list (status, coverage, mission/resource counts) makes the scope concrete. The 'caller's own' qualifier implicitly separates it from detail-oriented siblings like getWishDetailsTool, but no sibling is named explicitly.

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

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

Gives a clear use case: answering 'what did I ask for' and selecting the wish a follow-up refers to, which usefully routes the agent toward this list tool rather than a detail tool. No explicit negative guidance or named alternatives, so it stops short of the top band.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real semantic context beyond that: the result is scoped to proposals where the caller is the proposer, and each entry carries a status. It says nothing about ordering, volume, or pagination, which is the only 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?

Three short sentences, front-loaded with the scope, then the use case, then the exclusion, followed by a docs link. Nothing is padded, though the "concierge" framing costs a beat of parsing before the concrete meaning lands.

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 input parameters and no output schema, the description carries the burden of describing what comes back, and it does: what someone asked the caller to provide, what the caller offered, and the status. Combined with annotations, an agent has everything needed 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 nothing for the description to disambiguate; the baseline for a parameterless schema applies. The description correctly implies no filtering input is available (the list is implicitly scoped to the caller).

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

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

The description names a specific verb+resource (list every proposal the caller is the proposer of) and pins the perspective: the supplier side, not the requester side. It also distinguishes itself from the responding flow (dismissOfferTool), so an agent can separate it from listMyWishesTool 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?

It gives a concrete use case in the user's own words ("who wants something from me") and an explicit exclusion ("Responding to one happens on its page, not here"), which steers the agent away from treating this as an action tool. It does not name the specific sibling tool that performs the response, so routing is implied rather than explicit.

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

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

Annotations already declare read-only, idempotent, non-destructive, and non-open-world behavior. The description adds valuable context beyond annotations: the members-only access requirement, the categories of resources returned, and a documentation link. It does not detail pagination or exact return shape, but the bar is lower given 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 front-loaded with what the tool lists, followed by usage, access constraint, and docs link. The first sentence is a dense enumeration that could be slightly tighter, but no sentence 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?

For a simple one-parameter list tool with no output schema, the description supplies enough context: what it returns, when to use it, and the members-only restriction. Minor gaps like pagination or output format are not disqualifying given the tool's simplicity and annotation coverage.

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

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

Schema description coverage is 100%, and the single projectId parameter is documented in the schema as coming from findUserProjectsTool. The description adds no additional parameter meaning or syntax, so the 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?

States a specific verb (List) and resource (rikma resources: links, in-progress resources, open resources, products), making the scope unambiguous. It also contrasts itself with suggestion behavior ('before suggesting one'), implicitly distinguishing it from proposeProjectLinkTool.

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 a clear use case ('check whether a rikma already has a website/repo before suggesting one') and a prerequisite ('Members only'). It does not explicitly name alternatives or state when not to use this tool, so it stops short of 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, idempotentHint, non-destructive and closed-world, so safety is covered. The description still adds value beyond them: it discloses the membership authorization requirement and enumerates the returned fields (id, name, slug, parent), which is meaningful given there is no output 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?

One dense but well-ordered sentence: the resource and scopes come first, the returned fields next, the access constraint last, followed by a docs pointer. No filler, though the stacked parentheticals make it slightly harder to scan than a two-sentence split would 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?

For a single-parameter, read-only list tool with no output schema, the description supplies everything an agent needs: what is listed, the two scope values, the shape of each returned record, and the membership requirement. Nothing material is left unstated.

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

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

With a single parameter at 100% schema coverage, the schema already explains that projectId comes from findUserProjectsTool and requires membership. The description only echoes 'this rikma' and 'Members only', adding no format or sourcing detail beyond the structured field, so the 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?

States a specific verb and resource ('List the categories a product of this rikma can be filed under') and immediately disambiguates the two scopes it returns: the rikma's own ('rikma') and platform-wide ('platform'). This separates it cleanly from sibling tools like listRikmaProductOptionsTool, listRikmaProductVariantsTool and setProductCategoriesTool.

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?

Adds a real precondition ('Members only') that tells the agent the call will fail for non-members, but gives no explicit routing guidance such as when to call this versus setProductCategoriesTool (which presumably assigns categories) or the product-listing tools. Usage is implied by the listing verb rather than stated.

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 openWorldHint=false, and the description does not contradict them. It adds useful behavior beyond that: the sort order ('needs attention first, then whatever waited longest'), the exclusion of contact details, and the members-only requirement.

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 purpose, then row shape, then sort order, then the constraint and docs link — a logical order with no filler. It is dense, packing many facts into three sentences, but every clause carries information an 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?

There is no output schema, so the description bears the full burden of describing return shape, and it does so thoroughly by enumerating each row field and the stage/attention vocabularies. Combined with the members-only note and the pointer to getLeadTool for detail, nothing essential to correct invocation 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 every parameter, including the view enum, is documented in the schema itself, so the baseline is 3. The description adds context around output fields (stage values, ownerId null meaning, attention reasons) rather than enriching the input parameters, so it does not exceed the schema on this dimension.

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 and resource ('List the enquiries (leads)') and defines scope precisely: pre-money leads a rikma works on, covering both inbound people and concierge wish proposals where the rikma is a candidate. It also distinguishes itself from the single-lead sibling by saying 'open one lead for that,' which maps to getLeadTool.

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 names a clear alternative for the one thing this tool cannot do ('No phone or email here — open one lead for that') and states the access prerequisite ('Members only'). It stops short of explicitly contrasting when to use this list versus other pipeline tools such as getWishDetailsTool or listMyWishesTool, and leaves view selection entirely to the schema.

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 and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: a members-only access requirement, that buyer contact is sensitive, and that it never leaks into webhooks — useful constraints beyond 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?

Front-loaded with the verb and scope, which is good, but the body is a single dense run-on sentence carrying a full return-field enumeration. The field list earns some place since there is no output schema, yet the structure is a wall of text rather than scannable.

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 usefully enumerates the returned fields and flags the sensitive buyer contact, plus the members-only constraint. That is close to complete for a list tool; pagination/default behavior is left to the schema's limit description.

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 four parameters (limit, status, projectId, oversoldOnly) are already documented in the schema. The description restates the status enum values but adds no filtering semantics beyond what the schema 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?

States a specific verb (List) and resource (paid orders reported by the storefront for one rikma), so the agent knows it retrieves order records. It does not, however, explicitly distinguish itself from the singular sibling getRikmaOrderTool, leaving the list-vs-get choice to inference.

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

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

Usage is implied: 'for one rikma' scopes it to a project and 'Members only' states an access prerequisite. There is no explicit when-to-use guidance, no exclusion, and no routing to getRikmaOrderTool or updateRikmaOrderStatusTool for adjacent tasks.

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, idempotentHint, and non-destructive flags. The description adds meaningful non-structured context: 'Members only' discloses an authorization requirement, and it enumerates what the return payload conceptually contains (conversation, open missions, resources, formed objects). It doesn't cover pagination, but the auth constraint and content shape are valuable additions beyond 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 core purpose, followed by a gloss of what a 'process' means, usage guidance, and access constraint. The em-dash phrase defining 'processes' is slightly verbose but earns its place by disambiguating a domain-specific term. The trailing docs URL is short and useful.

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 list tool with one fully documented parameter and annotations covering the safety profile, the description supplies everything needed: what it returns conceptually, when to call it, and who can call it. Only return-format/pagination details are absent, which is acceptable given the low complexity.

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% – projectId is fully documented in the schema as 'Rikma (project) id.' The description adds no syntax, format, or constraint details for the single parameter, so the baseline of 3 is appropriate when the schema does all the work.

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 (List) plus resource (a rikma's processes) with a clarifying definition of what a 'process' is ('open-ended threads... an approach to a partner, a launch, a funding attempt'). This distinguishes it clearly from siblings like startProcessTool, attachToProcessTool, and listProjectResourcesTool.

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?

Explicit when-to-use is given: 'Use it to see what is already in motion before starting something new.' This routes agents away from redundant creation calls and toward this reconnaissance tool, with no ambiguity about the trigger condition.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavior the annotations cannot: the 'Members only' authorization requirement and the semantic context that these axes are what a variant's axisKey is constructed from.

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 resource being listed and stays compact across three dense sentences plus a docs link. Slightly jargon-heavy ('axisKey', 'product.options'), but every sentence carries information and none repeats the schema.

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 usefully sketches the return shape (value, label, hex, image) and the access constraint, which is adequate for a small vocabulary lookup. It omits any note on ordering, size, or pagination of the returned option set.

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

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

There is a single required projectId with 100% schema description coverage, so the schema already documents the parameter. The description adds no format, scope, or sourcing guidance for projectId, which matches the baseline 3 for high 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?

States a specific verb and resource: list the product-option vocabulary (axes like size/colour with their values) for one rikma. It also positions the tool against siblings by explaining this is the axis set that product.options declares and that variant axisKey values are built from, which is exactly what distinguishes it from listRikmaProductVariantsTool and getRikmaProductTool.

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 a concrete when-to-use: check what size M really is before writing a variant that claims it, plus a 'Members only' access condition. It does not name an explicit alternative or a when-not-to-use case, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them: 'Members only' (an auth requirement) and the archived-visibility behavior tied to includeArchived.

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 action and scope, then the field inventory. The long enumeration is justified because there is no output schema, though the sentence is dense enough that a reader must parse carefully.

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 return-value burden and does so by listing name, price, pricing mode, status, archived, kind, quantity semantics (-1 = unlimited), stock fields, hasVariants, and variant fields. Auth, scoping (one rikma via projectId from findUserProjectsTool), and sequencing are all covered; ordering/pagination 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 description coverage is 100%, so all four parameters (kindOf, search, projectId, includeArchived) are already documented with filters, casing behavior, and defaults. The description adds no parameter syntax or format detail beyond the schema, so the 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?

States a specific verb and resource (list the products of one rikma for the merchant) and enumerates the exact fields returned. It explicitly distinguishes itself from the public catalog ('not the public catalog'), which separates it from siblings like searchCatalogTool and getRikmaProductTool.

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 a clear call-order rule: 'Call it first to see what you have on the shelf before creating, editing stock or checking orders,' which routes the agent to this tool ahead of create/update/stock operations. It does not name the narrower siblings (getRikmaProductTool, listRikmaProductVariantsTool) as alternatives for single-product or variant lookups.

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 read-only, idempotent and non-destructive behavior, and the description adds meaningful context beyond them: 'Members only' auth, the formula 'quant (-1 unlimited)', and the semantic weight of 'This is the truth the checkout consults'. It does not disclose any rate/limit or pagination behavior, so it falls short of 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?

One densely packed sentence that front-loads verb+resource, then the returned fields, then behavioral notes and a doc link. The long field enumeration is justified because there is no output schema, but the run-on construction is slightly harder to parse than a tighter phrasing would 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?

For a two-param, no-output-schema read tool, the definition covers everything an agent needs: what it lists, the fields it returns, the shop-domain meaning, the membership requirement, and a docs link. Annotations carry the safety profile, so nothing material 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 both projectId and productIds are already documented, including the cross-reference to listRikmaProducts. The description only loosely reinforces this by scoping variants to 'products of one rikma' and naming productId among returned fields; it adds no syntax or constraint detail, so 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?

States a specific verb (List) and resource (variant rows / product-variant / SKU) scoped to 'products of one rikma', and even enumerates the returned fields. This clearly distinguishes it from listRikmaProductsTool and listRikmaProductOptionsTool, which operate on products and options rather than SKU-level variants.

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?

Adds an auth prerequisite ('Members only') and implies the input by saying variants belong to products of one rikma, but never states when to prefer this over listRikmaProductsTool or getRikmaProductTool. Usage is inferable rather than explicit, which fits the 'implied usage' bar.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes nothing beyond that — no note on pagination, default limit behavior, or result ordering — so it adds no behavioral value over 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?

One short sentence with the action front-loaded, followed by a documentation link. It is appropriately sized, though the trailing URL is slightly noisy.

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 five-parameter, zero-required listing tool with full schema coverage and covering annotations, the description is minimally adequate: the structured fields supply limits, filters, and safety semantics. It is not misleading, but it omits any mention of result shape or default-limit implications for an agent that needs 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?

Schema description coverage is 100% and every parameter (limit, filter enum, projectId, missionName, projectName) is documented in the schema itself. The phrase "various filtering options" adds no syntax, default, or matching-behavior detail beyond it, so the 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?

The description states a specific verb+resource ("List user missions") and mentions filtering, which is enough to understand the operation. However, it never distinguishes itself from close siblings such as getMemberMissionsTool or findMissionTool, leaving the agent to guess which listing tool is appropriate.

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?

"with various filtering options" is the only usage hint; there is no when-to-use, no prerequisite, and no named alternative among the many sibling list/find tools. An agent gets no routing guidance at all.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), and the description adds meaningful context beyond them: a non-obvious hidden state transition on another entity (the lead becomes "contacted" on first outgoing contact) and a members-only authorization scope. It stops short of describing repeat-logging behavior or error conditions, so a 4 rather than 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?

Three tight sentences, front-loaded with the action, then the side effect, then the constraint, with a docs link at the end. No sentence is filler and nothing important is buried.

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 6-parameter mutation tool with full schema coverage, annotations, and no output schema, the definition covers purpose, constraints, and the key side effect, which is enough to call it correctly. It leaves minor gaps around whether the tool returns anything and how duplicate entries behave.

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 every parameter is documented in the schema, including the direction enum meaning and the 30-day-back limit on 'at', so the baseline applies. The description adds only marginal meaning beyond that, mainly tying direction='out' to the "contacted" transition; it says nothing about 'body' length or 'projectId' scope.

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

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

States a specific verb and resource ("Record a conversation ... in the lead's log") and enumerates the concrete variants (call, WhatsApp, email, meeting, note), which lets an agent distinguish it from the read-side siblings listRikmaLeadsTool and getLeadTool 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 real usage constraints: "Only log what the member told you happened; never invent a conversation" and "Members only", plus the side effect that a first outgoing contact marks the lead "contacted". It does not explicitly say when not to use it or name an alternative tool (e.g., reading a lead's log via getLeadTool), which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the tool performs no navigation itself and the return value carries the path to append to https://1lev1.com, which is exactly what an agent needs to know before calling it.

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 purpose and the key caveat, then parameters, then the sibling pointer and docs link. The semicolon-chained sentence is dense but every clause carries information; a small trim is possible but nothing 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?

For a no-output-schema, three-parameter link builder, the description covers purpose, non-side-effect behavior, parameter usage, result shape, and where to find valid inputs. 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% (baseline 3), and the description goes further by giving concrete path examples ('/lev') and clarifying the relationship between url and idPr ('/moach/<projectId>' with idPr), which the schema alone does not spell out. It stops short of full format/validation detail.

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

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

States a specific verb+resource ('turn a 1lev1.com page into a link') and immediately disambiguates scope with 'it does not open anything by itself'. An agent can tell this apart from siblings like getSitePagesTool or openRikmaConversationTool 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?

Explains the intent (produce a link to give the user) and points to the alternative for enumerating paths ('getSitePagesTool lists the valid paths'). No explicit when-not condition is given, but the operating context is clear enough to select correctly.

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=false, idempotentHint=false and destructiveHint=false, so mutation semantics are partly covered. The description adds genuinely new context: the thread is auto-created on first open (a side effect), and access is "Members only," which is an auth constraint not present 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-loads the resource and its scope, then the usage rule, then the return contract. Mostly efficient, though the parenthetical "where it stays on record" is decorative and could be cut.

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 the get-or-create side effect, the members-only constraint, and the return value (forumId) despite there being no output schema, and links to docs. Complete enough for an agent to call it correctly; only the exact error/empty behavior is unstated.

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?

Single parameter with 100% schema description coverage, so the schema already documents projectId as the rikma id. The description adds no syntax, format, or sourcing guidance beyond that, which matches the baseline 3 for a fully documented parameter.

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

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

States a specific resource (the rikma's own general conversation) with a clear scope boundary: the thread belonging to the whole rikma rather than to a mission, act or decision. An agent can distinguish it from siblings like listMyConversationsTool and readConversationTool 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 when to use it ("what are we doing next" talk) and when not to (anything about a specific mission, decision or profit split belongs in that thing's own thread). It also tells the agent what to do next with the result, naming readConversation and postConversationMessage as consumers of the returned forumId.

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 cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), and the description adds genuinely non-obvious behavior: results are deduplicated against existing project content, nothing is persisted in the project, the return is a reviewUrl with per-row approval, and error.retryable signals whether a retry helps. These details go well 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?

The core action and the createPlanBoardTool alternative are front-loaded, and each sentence (dedup, review flow, prerequisite, retry semantics, docs link) carries distinct information. It is on the longer side, but nothing is redundant.

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 explains the return value (a reviewUrl for per-row approval), the deduplication behavior, the error contract, and the prerequisite tool. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents text, title, and projectId, and the description largely repeats this (projectId required, richer brief is better). The findUserProjectsTool hint for projectId adds slight value, but with the schema doing the heavy lifting 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: 'Turn a free-text brief into a planning board' with the concrete outputs (proposed missions, chores/acts, resources). It explicitly distinguishes itself from the sibling createPlanBoardTool, so an agent can route correctly 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?

It gives explicit when-to-use ('the user describes something in loose words'), when-not-to-use ('if the conversation already holds a concrete breakdown... use createPlanBoardTool instead'), and a prerequisite (requires projectId, use findUserProjectsTool first if unknown). This is a complete routing decision.

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 a non-read-only, non-destructive, non-idempotent write. The description adds genuinely new behavior: other participants are notified, and the message is visibly marked as written through an agent. It does not state what happens on failure or whether repeated posts duplicate, but the added side-effect disclosure is substantial.

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 action, then the notifications side effect, then the usage constraints, in three tight sentences with no filler. Slightly long, and the docs URL is a minor appendage, but every clause carries decision-relevant 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?

For a two-parameter, non-destructive write with full schema coverage, the description covers purpose, side effects, and invocation boundaries. No output schema exists and none is needed for a post-only 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?

Schema description coverage is 100% for both parameters (forumId sourced from listMyConversations, message in the user's own words/language, plain text, 4000 max). The description echoes the 'in the user's own words and language' intent but adds no format or syntax beyond the schema, so 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?

States a specific verb and resource ('Post a message, as the user, in a conversation (forum) they take part in') and grounds it with three concrete examples (mission update, decision thread answer, profit split note). It is immediately distinguishable from siblings like readConversationTool and openRikmaConversationTool.

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 trigger ('ONLY when the user asked to say or record something') and two explicit exclusions ('never to think out loud', 'never to agree or refuse on their behalf'), plus the reason (approvals are the user's own click). This is the strongest form of 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 (readOnly=false, destructive=false, idempotent=false) it discloses what actually happens: nothing is created until the recipient claims it, the caller loses access once claimed, the call is refused when the email matches the user's own, and links expire after 14 days. That is exactly the mutation/consequence 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?

Front-loaded with purpose and the two returned links, then when-to-use, then safety constraints — a sensible ordering. It is a single dense paragraph that runs long, and the parenthetical enumerations of editable items are slightly padded, but nearly every clause carries operational 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?

For a 9-parameter tool with a deeply nested blueprint and no output schema, the description explains the returned artifacts (previewUrl, manageUrl, plus signupUrl/receiveUrl), their access model, and expiry — the critical gaps are closed. Remaining shortfall is that several optional top-level parameters are never explained.

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

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

With only 44% schema coverage, the description carries real weight: it tells the agent to pass the other person's name and email as given, to reuse prepareSignup's intent and blueprint shape, and to include missions with hours and ratePerHour so the recipient can tweak immediately. It leaves lang, wishText, aboutText, and countries unaddressed, so it doesn't fully close the coverage 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 concrete verb and resource ("Prepare a rikma on 1lev1 for ANOTHER person") with an explicit scope contrast against the user's own case. It immediately names the sibling it is not (proposeRikmaBlueprint) and distinguishes itself from prepareSignup by reference, so an agent can route correctly 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?

Gives explicit when-to-use triggers (a member markets 1lev1 and sets up a new customer's business, or helps another member get started), an explicit when-NOT ("NEVER use it for the user themselves... use proposeRikmaBlueprint"), and an ambiguity rule ("If it is not clear who the rikma is for, ask before 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?

Annotations already declare readOnlyHint/idempotent/non-destructive, and the description adds genuinely new behavioral facts: nothing is created yet (status 'prepared' until publish), catalogue name uniqueness is reused automatically, never rename to force uniqueness, and the returned url must be passed through verbatim. That is well beyond what the annotations 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?

Front-loaded with purpose and the primary routing rule, with dense but non-redundant sentences. It is on the long side and the catalogue-uniqueness passage is somewhat sprawling, but nearly every sentence carries operational 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?

There is no output schema, yet the description explains the return value (url, used as-is), the deferred-creation semantics, required inputs and the sibling tools to consult first. For an 8-param tool with rich annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and each parameter (roles, skills, valph, nhours, descrip, workways) is documented in the schema itself. The description only adds the projectId sourcing hint and the catalogue-matching nuance, 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?

Opens with a specific verb+resource ('Prepare the mission creation form') and states the concrete output (a pre-filled link). It goes further by defining what a mission is ('work that needs an implementer to be found'), which cleanly distinguishes it from createTaskTool and the get* inspection 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?

Explicit when-to-use ('when the user should review and confirm the mission before it is published'), explicit alternatives ('create a task (act) on it with createTaskTool instead'), and a prerequisite check ('Check the rikma's open missions (getProjectDetailsTool) first'). It also names findUserProjects as the way to obtain a missing projectId.

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 past the annotations: states the mutation is incomplete by design ('You cannot sign, set a password or confirm the email for them, and nothing is created until they do'), gives link lifetimes ('valid 24h'), and describes the post-confirmation landing state. It also discloses the return payload (previewUrl, manageUrl, signupUrl) despite there being no output 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?

Front-loaded correctly (purpose, then eligibility, then consent, then intents), but it is one dense run-on paragraph where the intent enumeration is buried in semicolon clauses. It also repeats itself: previewUrl/manageUrl are explained twice and 'signupUrl' is introduced then re-recommended at the end.

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 8-parameter tool with a deeply nested blueprint and no output schema, the description covers the risky parts well: consent, input provenance, intent-to-payload mapping, and returned links. It is only short of complete because `lang` is undocumented and country-handling is left implicit.

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

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

With only 38% schema coverage, the description carries real weight: it defines all five intent values and, critically, binds each to the right payload (blueprint for business/partnership/idea, aboutText for join, wishText for order) and warns against sourcing name/email from memory. The gap is `lang`, which is never mentioned, and `countries` gets only an indirect mention ('prefilled with their name, email and countries').

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?

Opening sentence gives a specific verb ('Prepare'), a specific resource ('a 1lev1 signup') and a hard scope condition ('for a person who has NO 1lev1 account yet'), so the agent can tell this apart from prepareForSomeoneElseTool or proposeRikmaBlueprintTool without opening a schema. The 'one screen' framing further explains what 'prepare' actually produces.

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?

Explicit gating on both sides: use only when the person's own request matches one of three named 1lev1 use cases, 'Do not bring it up in any other conversation', and a mandatory consent step ('tell the person what will be sent and get their go-ahead'). It also excludes this tool when the person already has an account and points at proposeRikmaBlueprintTool as the shape reference for the blueprint payload.

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 partial-failure semantics ("Every item is answered on its own (results[i]); one failing item never stops the others") — a property no annotation conveys and which directly affects how an agent should read the response. It also explains the per-product proposal model (own clock and vote), the immediate-apply exception for personal products, and the membership requirement. idempotentHint=false is consistent with the described propose-per-product behavior.

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

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

Three front-loaded sentences that earn their place, with the cap, rikma scoping, and per-item isolation stated first. The parenthetical about editObject ("one decision per object, with its own clock and vote") is slightly jargon-heavy and could be tightened, but it carries real domain meaning.

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 batch mutation tool with nested items and no output schema, the definition covers the essentials an agent needs: the 50-item cap, the single-rikma constraint, membership, per-item results, and independence of failures. What is missing is minor — it does not preview what a returned proposal contains or how to confirm the outcome after the call.

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

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

With only 50% schema description coverage, the description does add useful meaning: it clarifies that items is a list of per-product edits, capped at 50, all bound to a single rikma, and that each entry produces its own proposal. It does not explain the individual edit fields (name, price, reason, categories, pricingMode) or their differential behavior, leaving that half of the semantics to the schema, so a 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?

States a specific verb and resource ("proposeProductEdit for up to 50 products of one rikma in one call"), which both identifies the operation and implicitly distinguishes it from the single-item sibling proposeProductEditTool. The batch scope and the one-rikma binding are stated up front, so an agent can tell it apart from createRikmaProductsBatchTool or updateRikmaProductTool 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 a clear operating context: "one rikma", max 50 products, and the constraint "Members only", plus the crucial domain rule that a proposal belongs to one product, so each product gets its own proposal. It does not explicitly say "use proposeProductEditTool instead for a single product" or state when-not to use this tool, which keeps it below 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?

Without an output schema, the description carries the disclosure burden and does it well: it explains that a proposal is created, names the returned fields (proposalId, silenceApprovesAt, voteUrl), states the caller never approves, and flags the single-open-proposal constraint. Annotations only say the call is not read-only and not idempotent; the description adds the real behavioral contract.

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 main action is front-loaded in the first sentence and the rest is dense with necessary conditional behavior. It is somewhat compressed into run-on clauses with internal jargon ('restime', 'editObject') and typos ('rikma'), which costs a little clarity but not much 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?

Covers the mutation's effect, the proposal lifecycle, the membership prerequisite, the one-open-proposal limit, and points to external docs — enough for an agent to call it correctly. Minor gaps remain around what happens on failure or which fields are required versus optional, though the schema handles the latter.

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 labels name/price/descrip as 'A term', categories as 'Operational — applied at once', and pricingMode as personal-products-only. The description restates that terms become a proposal, which is useful framing but largely duplicates structured data. No new syntax, format, or validation meaning is added 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?

Opens with a specific verb+resource and enumerates exactly which fields can change (name, description, price, pricing mode, categories). It also splits behavior by product type (rikma vs personal), which an agent needs. It does not distinguish itself from close siblings such as updateRikmaProductTool, setProductCategoriesTool, or proposeProductEditsBatchTool, so the boundary is left to inference.

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 usage context: terms become a proposal on a rikma product, apply immediately on a personal product, categories always apply at once, and members only. It also states a precondition — one open proposal per product, answer it first if one exists. The gap is that it never names the alternative tool to use when a direct update or a batch edit is what's wanted.

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 generic mutation profile (readOnlyHint=false, idempotentHint=false). The description goes well beyond that: in multi-member rikmas, website and Facebook changes open a member vote where silence approves on clock expiry, while other links change directly. That voting/approval semantics is exactly the kind of non-obvious behavior an agent needs.

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 action and target, then layers permission and voting behavior, ending with a docs link. Dense but every sentence carries information; the trailing docs URL is the only mild 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?

With no output schema, the description covers action, target, permissions, and the vote-vs-direct distinction well. It stops short of describing the response (e.g., whether a proposal id is returned when a vote opens), which an agent invoking a mutation tool would benefit from.

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 itself documents url (empty string clears), kind (enum), and projectId. The description adds nothing beyond what the schema already states, 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?

States a specific verb pair (set or clear) and the exact resource (one of a rikma's named links), enumerating the link kinds. An agent can distinguish this from sibling tools like listProjectResourcesTool or createProjectTool immediately.

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 sequencing guidance ('Check listProjectResourcesTool first - the link may already be there') and a gate ('Members only'), plus the condition that triggers a vote. It stops short of stating when not to use the tool, but the routing 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?

Annotations only say this is a non-destructive, non-idempotent write; the description goes much further, explaining that nothing is created and no email is sent until the user clicks reviewUrl, that partner invitation emails are sent server-side on creation, and that the result reports delivery plus a shareable join link. That is exactly the side-effect detail an agent needs before invoking.

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 trigger are front-loaded and the bullets carry real operating rules, but the text is a dense wall that repeatedly restates the same prohibition on inventing prices and emails rather than stating it once. It reads partly as workflow coaching rather than tool contract, which lengthens scan time without adding new 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 7 parameters, deep nesting, no output schema and no param descriptions in the schema, this is a complex tool — and the description covers the workflow, the reviewUrl handoff and the return behavior ('reports delivery and includes a join link'). The remaining gap is the un-narrated `fields` sub-object and its enums, though those are largely top-level metadata.

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 only 29%, and the description compensates well for the semantic core — products-first with price/keywords/categories, holder 'me'/'open'/'partner' plus partnerRef, per-period pricing for recurring costs, and `why` on each row. But the entire `fields` object (track, vals, restime, currency, location, descripFor, linkToWebsite, publicDescription) and the cryptic `restime` enum are left unexplained, so a meaningful chunk of the payload is documented nowhere.

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 states a specific verb and resource: turn a business/partnership/idea into a draft rikma containing products, missions, resources and partners. It also separates itself from the sibling `prepareForSomeoneElse` ('a rikma prepared for another person is prepareForSomeoneElse') and from creation tools ('Nothing exists ... until the person creates it there').

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?

Three concrete triggering situations are given ('add their business so the concierge can find and order from them', 'see how their partnership would look', 'break an idea down and recruit partners'), plus guidance on when to pass projectId and which sibling handles the prepared-for-someone-else case. There is no explicit 'do not use this for X' exclusion, so it stops short of 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?

Beyond the annotations (readOnly, idempotent, non-destructive), it discloses that pricing is read from the rikma's own catalog so free-delivery thresholds apply as at checkout, that the district is resolved from the city, that membership is required, and enumerates the unavailability reasons returned. This is substantive behavioral context the annotations alone 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?

Front-loaded with the verb and a concrete example, with no filler sentences. It is a single dense paragraph packing in return-value and eligibility detail; readable but could be broken up for faster scanning.

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 fully by enumerating return content (options, fee, free flag, amount-to-free, ETA, dispatch day, unavailability reasons). Nested parameters (items, address) and the optional address path are both covered, so an agent has everything needed to call and interpret it.

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 meaning: productId/variant pairing from listRikmaProducts-style ids, quantity semantics, and the fact that a city alone is sufficient inside Israel. It stops short of documenting item limits or optional-field nuances beyond what the schema already states.

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 ('Price delivery of a cart from one rikma to an address') and grounds it with a concrete user question ('how much is delivery to Haifa?'). This clearly separates it from siblings like getShippingConfigTool (configuration) and listRikmaProductsTool (catalog lookup).

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 a clear usage context ('Members only; read-only — nothing is ordered') and explains the address requirement including the optional-address case for pickup/digital. It does not explicitly name alternative tools (e.g. getShippingConfigTool for config, searchCatalogTool for finding products), so routing is slightly inferred rather than spelled out.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavior annotations do not: messages are returned newest-last and each is attributed to its author, plus the participation restriction. It does not describe truncation or error behavior when the forum is inaccessible.

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 short sentences plus a docs link, with the purpose and return shape front-loaded ahead of the usage guidance. No filler or restated name/title content.

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

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

There is no output schema, yet the description supplies the return shape (messages in order, with authors) and the intended use, which is enough for a two-parameter read tool. Minor omissions remain, such as whether it errors or returns empty for a forum the caller cannot access.

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

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

Schema description coverage is 100%, with both forumId (source: listMyConversations) and limit (most recent, default 30) documented in the schema itself. The description adds virtually nothing about the parameters beyond the ordering detail 'newest last', so the 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?

The description gives a specific verb and resource ('Read one conversation (forum)') and scopes it to conversations 'the caller takes part in', which separates it from listMyConversationsTool's plural listing. It also states the returned content (messages with authors, newest last). It stops short of naming a sibling explicitly, so it is clear but not fully differentiated.

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?

'Use it before answering in a thread, so the reply fits what was already said' gives a concrete triggering condition, which is more than most read tools offer. It gives no exclusion or explicit alternative, though the schema's forumId note points at listMyConversationsTool as the source of the id.

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

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

Annotations already cover the mutation profile (readOnlyHint=false, destructiveHint=false, not idempotent), so the description's added value is the key behavioral fact that a model interprets the free text rather than the caller naming ops. It omits what happens on failure or a version mismatch, so it stops short of full disclosure.

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 plus a docs link, with the differentiation from setAssistantItems front-loaded. Slightly dense with nested quotes, 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?

For a model-backed mutation with no output schema, the description covers what the tool does and when to use it but not the prerequisites (a session must already exist) or the meaning of expectedVersion. An agent can invoke it, but may not handle version conflicts or the assistant session lifecycle 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 0% across three required params. The quoted example ('that's right, drop the second, add photography') usefully conveys that instruction is natural-language text relative to a list, but sessionId and especially expectedVersion (an optimistic-concurrency token) are left completely unexplained.

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 (change a list) with a concrete input example, and explicitly separates itself from setAssistantItems. 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?

Explicit routing rule: 'Prefer setAssistantItems when you can name the ops yourself; this one runs a model.' It names the alternative and the condition that selects it, which is exactly what usage guidance should do.

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 scoping side effects precisely ('saved as suggested directions only: nothing is created, and no mission, chore or resource comes out of this call'), naming the returned reviewUrl as the approval surface, and disclosing failure semantics ('error.retryable' indicates whether a retry can help). This clarifies what the non-readOnly, non-idempotent hints actually mean in practice.

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