welance/directory

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), and the description adds real domain context beyond them: this is the public catalogue, and it includes the acceptance threshold that decides whether a brief publishes. The main gap is that it doesn't describe the return shape or ordering, which matters slightly since there's 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?

A single front-loaded sentence that packs the resource, its fields and the downstream consequence of the threshold without a wasted clause.

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

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

For a zero-parameter, read-only, no-output-schema tool, the description covers enough: it tells the agent what the returned catalogue contains and why it exists. It could add a brief note on shape/ordering or a nudge to use it before publishing, but nothing needed to call it correctly is missing.

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

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

The tool takes no parameters, so there is no parameter semantics to explain and the baseline of 4 applies; the description correctly says nothing about arguments.

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 resource (the rule catalogue a brief is scored against) and enumerates its contents: ids, labels, weights and the acceptance threshold. It is clearly distinguishable from every sibling, which read briefs, pitches, bookings, teams or profiles rather than scoring rules, though it doesn't say so 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?

Usage is only implied: an agent can infer this is what you call to learn the scoring criteria before drafting or publishing a brief, but no when-to-use, when-not-to-use, or alternative (e.g. propose_brief_draft, read_brief) is 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?

The annotations already declare a safe, read-only, idempotent, closed-world operation, so the description does not need to explain side effects. It usefully discloses the subject matter of the returned information, but it does not describe the response format or other behavioral details 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 description is a single, front-loaded sentence that packs in audience, pricing, and the principal rule without filler. It is dense with multiple clauses but every clause contributes 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 zero-parameter informational tool with no output schema, the description provides the key content an agent would need to answer what the directory is. Safety behavior is already covered by annotations, and the remaining scope is sufficiently complete.

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

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

The tool has zero parameters and the schema coverage is 100%, so parameter semantics are inherently simple. The description does not need to explain parameters, and the baseline for a parameterless tool is appropriate 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?

The description clearly identifies the resource as the welance/directory concept and specifies the information covered: audience, pricing, and the human-principal rule. It does not explicitly differentiate this tool from informational siblings such as brief_rules, but the topical scope is still easy to identify.

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

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

The description provides no explicit guidance on when to call this tool, when not to, or which sibling tool is the better alternative for related information. Usage is only vaguely implied by the tool name and title.

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 closed-world, so the safety profile is covered. The description adds meaningful context beyond that: results are "anonymised server-side," which tells the agent not to expect identity data in the payload. It stops short of 5 by not covering pagination or result ordering.

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: the returned sets are front-loaded, then the privacy note, then the filter options. Every sentence carries information; only the slightly elliptical phrasing of the filter sentence costs it a point.

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 only two optional parameters and no output schema, the description covers the substantive questions: what sets are returned, what fields appear, and that data is anonymised. Missing are pagination/volume expectations and the no-filter default, which are relevant for a list tool but minor.

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

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

Schema description coverage is 0%, so the description must carry the load — and it does map the prose to the status enum values (open = "looking for a team," vetting, executed = "archive of delivered projects"). It also explains what `tangible` selects. It does not state the default behavior when no status is passed, but the enumeration implies all three sets.

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 (public briefs) and enumerates the three record sets it returns: open briefs seeking a team, vetting-stage ones, and delivered-project archive. It also names the fields carried (budget, sector, delivery team). It doesn't explicitly differentiate from the nearest siblings read_brief and read_pitchable_briefs, so it stops short of a 5.

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

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

"Filter by status or to tangible-world projects only" implies how to narrow results, but there is no explicit when-to-use guidance and no routing away from read_brief or read_pitchable_briefs. The agent must infer that this is the browse/discovery tool versus the single-record read tools.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds meaningful behavioral context beyond that: it stores nothing, calls no LLM, returns only matching teams with reasons and inferred defaults, and ends with a 'Start this brief' link. This is strong disclosure for a tool whose safety profile is already covered by annotations.

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

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

The description is compact and front-loads the core action, eligibility scope, and return behavior. The final sentence about the 'Start this brief' link is useful but slightly less essential to correct invocation. Overall, it avoids wasted language while remaining dense with relevant detail.

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 and only moderate parameter documentation, the description does a good job explaining the return shape: only matching teams, with reasons and inferred defaults. It also clarifies side effects (stores nothing) and model usage (no LLM). The main remaining gap is that the optional title parameter is not explained anywhere.

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

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

Schema coverage is 67%, so the schema already documents the main brief and language parameters. The description adds a useful length constraint for the required brief parameter and mentions inferred defaults, but it says nothing about the optional title parameter, leaving one parameter undocumented in both schema and description.

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

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

The description clearly states the specific action and resource: matching a draft brief against eligible anonymous teams to return only matching teams. It adds useful scope details such as brief length, reasons, and inferred defaults. However, it does not explicitly distinguish this tool from a potentially similar sibling like preview_teams.

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

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

The description implies this is for shortlisting teams from a draft brief, likely before publishing, and mentions that it uses the same derivation/matcher as publishing. But it does not explicitly state when to use this tool versus alternatives, nor does it name any sibling tools or exclusions.

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

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

Annotations already establish that this is a safe read-only, idempotent operation. The description adds meaningful behavioral context beyond those annotations: results are anonymous, rotate daily, are intentionally incomplete, and names/members are gated behind a mutual €30-per-side handshake.

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

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

The description is short and front-loads the core preview behavior before explaining the brief-first and handshake gating. Some phrasing such as 'specimens', 'supply', and 'handshake' is evocative but slightly less precise than it could 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?

Given the lack of an output schema, the description does explain the key return composition: two anonymous teams and a supply size, not the full board. It also explains the privacy and payment gating, though exact returned fields are still somewhat 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 zero input parameters, there are no parameter semantics for the description to clarify. The baseline score for a no-parameter tool is appropriate 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?

The description clearly states this previews a limited anonymous sample of two vetted teams plus the size of the supply, and explicitly says it never returns the whole board. It is more specific than the name/title alone, though it does not explicitly name a sibling tool or contrast itself with one.

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 when the tool is useful by explaining that the board is brief-first and full team details require a draft brief and handshake. However, it does not explicitly say when to use this tool versus siblings like directory_capabilities, match_brief, or list_open_briefs.

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 the €30 hold, its 7-day duration, the no-charge-until-mutual-accept rule, the no-show forfeiture and show-up credit, and that the call only stores a proposal with a review link in the result. That is exactly the financial and side-effect context an agent needs before invoking a non-readOnly, non-idempotent tool.

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

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

No filler sentences — every clause carries pricing, format, or lifecycle information — but the opening is a sentence fragment with the object before the verb, and pricing, format, and confirmation semantics are crammed into run-on sentences. The most important thing (what the tool does) is not front-loaded.

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

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

For a mutation tool with no output schema, the definition covers the action, constraints, financial side effects, and the post-call confirmation flow, plus a hint that the result contains a review link. It omits repeat-invocation behavior (idempotentHint is false) and what happens to the hold at day 7, which an agent might need.

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 schema coverage at only 25% (only summary is documented in-schema), the description carries the load for slots — ISO 8601, weekdays, on the hour, 09–18 CET, 3–10 business days out — far exceeding the schema's bare minItems/maxLength. appId is explained only loosely ('the person's own brief (appId)') and the note's 400-character cap is left to the schema, so it stops short of full compensation.

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 (propose a 30-minute call on a pitch tied to the person's brief via appId) with the required artifact (3+ concrete slots, optional note). It implicitly separates itself from propose_booking_accept by stating 'Stores a proposal only', but never names the sibling and the opening is a dangling fragment that delays the verb.

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?

Establishes clear context: use this as the client of a pitch on a brief, and only this side initiates the proposal. It clarifies that nothing is committed until the other party confirms on welance.com/directory, which steers an agent away from treating it as a confirmation step, but it never explicitly names propose_booking_accept as the follow-up 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?

Adds substantial behavior beyond annotations: €30 charge per side, no-show credit/forfeit rules, that the call only stores a proposal, that nothing happens until confirmation on welance.com/directory, and that the result includes the review link. This is exactly the kind of mutation-side-effect detail 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 core action and caller role, then packs the key financial and confirmation behavior into a short, information-dense description. There is no wasted text.

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

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

Covers the financial consequences, no-show rules, proposal-only nature, external confirmation requirement, and result content. With annotations already covering safety and idempotency hints and no output schema present, this is complete enough for an agent 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 only 33%, but the description meaningfully explains bookingId as the booking context and slotId as one of the client's offered slots. The remaining parameter, summary, has its own schema description, so the combined coverage is strong even though the description itself does not describe it.

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

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

States a specific action (propose accepting a slot) scoped to the team on an existing booking, using bookingId and the client's offered slotId. This distinguishes it from sibling tools like propose_booking and read_booking without needing 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?

Clearly establishes the usage context: the caller is the team on a booking and is accepting one of the client's offered slots. It does not explicitly name alternatives or exclusions, so it falls short of 5 but gives enough context to select it 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?

Beyond the annotations (non-read-only, non-destructive, non-idempotent), the description adds real behavioral context: side effects are deferred until human confirmation, acceptance fills the brief editor, nothing is published, and the response includes a review link. It does not say what happens to prior or superseded proposals, which keeps 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?

Front-loaded with what the proposal contains, followed by side-effect and limit information. Slightly redundant: 'nothing is published' and 'Stores a proposal only. Nothing happens until...' make the same point twice.

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, and the description compensates by stating the result includes the review link. For a staged-write tool with a nested object parameter, the remaining ambiguity (answer key format, proposal lifecycle) is modest rather than blocking.

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 25%, so the description carries partial burden and does add meaning: 'per-rule answers' clarifies the answers object, and the 64,000 UTF-8 byte cap on the whole proposal clarifies how the fields interact. It still says nothing about the keys allowed in the nested answers object or about the required summary field, leaving real gaps.

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 ('a proposed update to the person's local brief draft') plus the fields it carries (title, markdown, per-rule answers). The clause 'nothing is published' implicitly separates it from the sibling propose_brief_publish, so an agent can distinguish the two 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?

Explains the operating model clearly: 'Stores a proposal only. Nothing happens until the person confirms it on welance.com/directory.' That tells an agent this is a staged, non-committing action. It never explicitly names propose_brief_publish as the alternative for actually publishing, so the routing guidance is implied 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?

The description adds extensive behavior beyond the annotations: confirmation required on welance.com/directory, a live score gate decides publishing, one-time email link with no sign-in, a 64,000 UTF-8 byte total limit, and that the result includes a review link. This is rich disclosure for a mutation tool.

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

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

The description is front-loaded with purpose, then behavior and limits, and every sentence earns its place. There is minor redundancy between 'Stores a proposal only' and 'Nothing happens until the person confirms it,' but overall it is efficient.

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

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

For a proposal tool with no output schema, the description covers the confirmation flow, score gate, email behavior, size limit, and review-link return. It could mention failure or rejection cases, but the essential caller context is present.

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

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

Schema description coverage is only 25%, so the description should compensate more. It does list title, markdown, and optional language and adds the 64,000-byte total constraint, but it omits the required 'summary' parameter entirely and provides no format details for the others.

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 specifies the verb (propose) and resource (publishing a brief to the board), and clarifies it stores a proposal only. It distinguishes from immediate publishing but does not explicitly name the sibling tool propose_brief_draft, leaving the agent to infer the contrast from the name.

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

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

The description implies usage through the confirmation flow and score gate, but never states when to use this tool versus alternatives like propose_brief_draft or propose_pitch_send. No explicit conditions or exclusions are given.

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 only say readOnly=false and destructive=false; the description adds the substantive behavior — the call stores a staged proposal, nothing is transmitted, and the person must confirm out-of-band at welance.com/directory, with a review link returned. It omits any warning that repeated calls are not idempotent (idempotentHint=false) and would create additional draft proposals.

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?

"nothing is sent," "Stores a proposal only," and "Nothing happens until the person confirms it" all restate the same non-transmission guarantee across three sentences. The opening is a noun fragment rather than a front-loaded verb, though the description is still short enough to scan.

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

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

With four required parameters and no output schema, the description covers the key unknowns: the approval model, the external confirmation step, and the fact that the result carries a review link. Missing only failure conditions (invalid briefId, team not owned) and the non-idempotency caveat.

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 50%: text and summary are documented in-schema, while briefId and teamKey are not. The description compensates by qualifying teamKey as "one of the person's teams" and briefId as "an open brief," which tells the agent the ownership and state constraints the bare integer/string schema does not.

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

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

The description states the resource precisely — an anonymous pitch draft for a team (teamKey) on an open brief (briefId) — and makes the draft-vs-send distinction explicit with "nothing is sent. Stores a proposal only." It never names the sibling propose_pitch_send, so the differentiation is inferable rather than declared.

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 useful preconditions (a team the person belongs to, an open brief) and describes the confirmation flow on welance.com/directory. However, it never tells the agent when to choose this over propose_pitch_send or propose_brief_draft, leaving the alternative selection 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 only say this is a non-read-only, non-destructive, non-idempotent write; the description goes well beyond that by disclosing that it stores a proposal only, that no side effect occurs until confirmation at welance.com/directory, that the brief owner then sees it, that each brief caps pitches at 10, and that the result contains the review link. That is exactly the behavioral context an agent needs for a two-phase write.

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 confirmation caveat, then the 10-pitch cap and return value. Dense with semicolons but every clause carries operational information; nothing is redundant with the title.

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

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

With no output schema, the description still tells the agent what comes back (the review link) and what does not happen automatically (no send until human confirmation). Combined with the capacity limit and anonymity rule, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 50% (only text and summary are described in-schema), and the description compensates by explaining teamKey ('one of the person's teams') and briefId ('an open brief'). It adds the anonymity constraint that shapes text content, though it doesn't restate length bounds or what an invalid/closed briefId does.

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 precise verb+resource: proposes sending an anonymous pitch for a team (teamKey) on an open brief (briefId). The scope ('anonymous', 'on an open brief') and the two-phase propose-then-confirm nature are spelled out, so an agent can tell this apart from a plain draft tool or a direct-send tool 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?

The description implies the use case ('on an open brief', 'a proposal to send') and warns that nothing happens until confirmation, but it never names an alternative such as propose_pitch_draft or read_pitchable_briefs, nor does it state exclusions (e.g., when a brief is closed or the pitch cap is already reached). Guidance is inferred 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?

The description adds substantial behavior beyond the annotations: it states the tool 'Stores a proposal only,' 'Nothing happens until the person confirms it on welance.com/directory,' and the result includes the review link. It also discloses that each changed field becomes a separate approval card, that inferred values are rejected for certain fields, and how team hourly rates override blended member rates.

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

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

The description is dense and long, but it is front-loaded with the core purpose and then organized by entity type and field group. Nearly every sentence carries useful constraints or routing information, though the semicolon-separated wall of detail could be easier to scan.

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

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

For a 10-parameter mutation tool with low schema description coverage and no output schema, the description is largely complete: it covers entity selection, field constraints, inferred-value restrictions, the proposal-only confirmation workflow, and the review link in the result. Minor gaps remain around the required summary parameter and some change metadata fields, but the schema fills those in.

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 10% schema description coverage, the description carries most of the semantic burden and does so well: it explains entity values, the changes array structure, skills rating and removal, addLangs/removeLangs two-letter codes, hourly_rate units and range, team hourly null-override behavior, and shipped-entry add/remove semantics. It does not explain the required summary parameter or the evidence, sourceId, and attachmentId fields in the description, leaving some schema-level details to the schema itself.

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: 'Proposed field changes to one entity,' and then enumerates exactly which entities and fields are covered. It makes the tool distinguishable from read_profile and other propose_* siblings by clarifying that this creates profile-change proposals rather than reading profiles or proposing bookings/pitches.

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

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

It gives clear routing guidance across entity types: person is the signed-in person's own profile, member requires teamKey + memberKey for a confirmed colleague, team requires teamKey, and organisation requires organisationId. It does not explicitly name sibling alternatives such as read_profile for viewing or state when not to use this tool, so it falls short of full when/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?

Goes well beyond the annotations: it discloses that nothing happens until confirmation, that the invitee gets an email only after confirming, that skill ratings are set later, and that the result includes the review link. This is meaningful side-effect and return context for a mutation tool, none of which the readOnlyHint/destructiveHint 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?

Three tight sentences that front-load the core action and then the critical 'proposal only' constraint. Dense but every clause contributes; nothing feels 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 mutation tool with no output schema and sparse schema coverage, the description supplies the missing behavioral essentials (deferred effect, result link) and most parameter identities. Only the 'summary' parameter's role and field formats are left unaddressed, a minor gap.

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

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

Schema description coverage is only 20%, so the description does useful work naming teamKey, name, email, and the optional role. However, it never explains the required 'summary' parameter (there is a schema description for it), and it gives no format or constraint guidance for the undocumented fields. Adequate but with a clear gap.

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

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

States a specific verb and resource ("a proposal to invite a person to one of the signed-in person's teams") and immediately clarifies the scope limitation ("stores a proposal only"), which is exactly what distinguishes it from the sibling propose_* variants and any actual-invite tool. An agent can tell what this does 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?

The description makes the usage context clear: it's a proposal that only takes effect once confirmed on welance.com/directory, so the agent knows this is the pre-confirmation step. It doesn't explicitly name a when-not condition or point to a specific alternative sibling, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely useful behavioral context by stating the result is scoped to the signed-in person's side of the booking, but it says nothing about behavior for missing/unauthorized ids.

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 front-loaded sentence with no filler; the resource and selector come first and the return content follows. The closing clause about 'which side the signed-in person is on' is slightly compressed but still 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 burden of describing return values and does so at a high level (slots, state, perspective). For a single-parameter read tool this is largely sufficient; only error/empty-case behavior is 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 0% for the single parameter, so the description must compensate. It does tie bookingId to 'the booking id' and implies it selects exactly one record, but adds no format, valid-range, or error semantics beyond the schema's integer 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 names a specific resource (one booking) selected by bookingId and enumerates what is returned: proposed slots, state, and the signed-in person's side. That is more than a restatement of the title 'One booking', though it doesn't explicitly name sibling reads like read_brief or list_open_briefs to differentiate.

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: the required bookingId signals 'call this when you have a known booking id'. There is no explicit when-to-use, when-not-to-use, or pointer to alternative tools such as list_open_briefs or propose_booking for other flows.

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 bar is lower. The description adds two useful facts beyond them — visibility limited to public briefs and the markdown body being included in the return — but says nothing about not-found/private-brief behavior or error handling.

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

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

A single dense clause that front-loads the resource and scope (one public brief, full body) before the lookup key. No filler sentences.

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, the description covers what is returned and the access scope. It is thin on edge cases (nonexistent id, non-public brief) and doesn't hint at response shape, though annotations and schema make the core call unambiguous.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does identify the single parameter (briefId) as the brief's identifier. However, it adds no format, range, or sourcing guidance beyond what the integer schema already encodes.

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

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

Specific verb+resource: read one public brief by id, with the added detail that the full markdown body is returned. The "one ... in full ... by its id" phrasing implicitly contrasts with list_open_briefs and read_pitchable_briefs, but it never names a sibling explicitly.

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

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

"By its id (briefId)" implies the prerequisite of already having an identifier, which distinguishes it from discovery tools, but there is no explicit when-to-use/when-not statement or named alternative (e.g., list_open_briefs for discovery, match_brief for relevance lookup).

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 closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the default multi-identity fan-out, and the fact that each invoice is tagged with {kind, id, label, vatMasked}. It does not say how many results come back by default or whether there is pagination beyond limit.

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 default-scope behavior is front-loaded before the per-parameter explanation, and every sentence carries information. The dense parenthetical asides (personal VAT plus companies they own or administer, the identity object) make the single paragraph slower to parse than necessary.

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, closed-world list tool with no output schema, the description supplies scope, filter semantics, value vocabularies, and the tag shape on returned records. The remaining unknowns — default page size, sorting, whether identity variants can be combined — are minor but real.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely does: identity ("all", "personal", "org:<organisationId>"), identities (array of personal/org ids), from/to (YYYY-MM-DD, inclusive), and limit (1–50) are all defined with formats and vocabularies the schema does not provide. The one omission is whether identity and identities are mutually exclusive or can be combined.

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 — the signed-in person's past invoices — and names the concrete artifacts returned (PDF and document links via pdfUrl/documentUrl). The scope statement (all billing identities by default) makes the tool unambiguous, and no sibling in the list touches invoices, so confusion risk is minimal.

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

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

Explicitly explains the default behavior ('without filters it covers every billing identity') and how each narrowing axis works, so an agent knows exactly what happens if it omits parameters. It never states a when-not-to-use case or names an alternative tool, but no sibling overlaps this capability, so the gap is small.

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 closed-world scope, so safety is fully covered. The description adds genuine value by enumerating returned content (outgoing applications with handshake and booking state, plus inbound anonymous pitches), but says nothing about volume, ordering, or pagination for what could be a large aggregate, and there is no output schema to fill that 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?

A single sentence with zero filler. The subject ('the signed-in person's pitches and bookings') is front-loaded and the two data categories follow immediately as elaboration, so the reader gets scope before detail.

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 and no output schema, the description carries most of the burden of explaining what comes back, and it does so reasonably well by naming both directions of data and the associated state fields (handshake, booking state). The remaining gap is aggregate behavior — result size, ordering, or whether anonymous pitches are summarized — which an agent would need for a tool that can return two different record types at once.

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, which is the baseline 4 case. The description correctly implies no input is needed because everything is derived from the authenticated identity, matching the empty schema.

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

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

States a specific verb implied by 'read' plus a clear resource: the signed-in person's pitches and bookings, split into applications sent by their teams and anonymous pitches received on their own briefs. It distinguishes itself from singular readers like read_booking or read_brief by scoping to the caller's own two-sided activity, though the phrase 'on both sides' is slightly awkward and requires the following clause to disambiguate.

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 'signed-in person's' framing implies this is a no-argument self-lookup, so an agent can infer it needs no identifiers or filters. However, no alternative is named: it never says whether to use this instead of read_booking for a specific bookingId, or instead of read_pitchable_briefs when browsing. Usage is implied rather than directed.

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

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

Annotations already establish safety as a read-only, idempotent, non-destructive, closed-world operation. The description adds meaningful behavioral context by explaining which facts are derived versus stored and that checklist items are marked met or missing, though it does not discuss permissions or error behavior.

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

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

The description is front-loaded with the core resource and then details returned fields, but it is a dense run-on sentence that could be more scannable. Every clause appears to add useful information, so it is efficient if not optimally structured.

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

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

With no output schema and zero parameters, the description carries the burden of explaining return values, and it does so thoroughly by naming each field group and the checklist statuses. Annotations cover the safety profile, so nothing essential is missing for correct invocation.

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

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

The tool takes zero parameters and schema coverage is 100%, so parameter semantics are not a concern. The description appropriately avoids redundant parameter information.

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

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

The description clearly identifies the resource as the signed-in person's teams and enumerates the returned contents, including derived facts and checklist states. It is specific enough to distinguish a read-my-teams operation from generic team listings, but it never explicitly contrasts itself with sibling preview_teams or other team-related tools.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as preview_teams or read_profile. Usage is only implied by the description of returned data, leaving the agent to infer the appropriate context.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so safety is covered. The description adds substantive behavioral context beyond that: results are scoped per team and pre-filtered on three eligibility criteria, which tells the agent the result set is already narrowed and needs no client-side filtering.

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

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

A single dense sentence with the scope (per team) front-loaded and the filter criteria trailing. Every clause carries information; nothing is repeated from the title. It is a sentence fragment, which is stylistically loose but not costly.

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 full annotation coverage, the description supplies what an agent needs: what is returned, per what grouping, and under which eligibility conditions. Only the concrete shape of the return (grouped by team object vs. flat list) is left implicit, which is a minor gap for a zero-input tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed — the signed-in person and their teams supply the implicit context.

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 (open briefs) and a precise scope: per team of the signed-in person, filtered to briefs still pitchable. The three qualifying conditions (not yet pitched, pitch slots left, language match) make it distinguishable from list_open_briefs and read_my_pitches. It does not explicitly name those siblings, which keeps it from 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 framing ('briefs that team can still pitch on') implies the use case — finding what to pitch — but there is no explicit statement of when to prefer this over list_open_briefs or read_my_pitches, nor any exclusions. Usage is inferable rather than instructed.

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 closed-world, so the safety bar is low. The description adds the key behavioral fact that annotations cannot convey: the result is scoped to the authenticated caller's own record, not an arbitrary user's, and it itemizes what state is exposed including verification state.

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 front-loaded sentence with a colon-list of fields and zero filler. It is a noun phrase rather than a full sentence, but every word earns its place and nothing 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?

With no output schema, the description's field enumeration is the only source of return-content information, and it is adequate for a zero-arg read. Minor gaps remain: no mention of behavior when no profile exists or whether fields can be empty.

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

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

Zero parameters and 100% schema coverage, so nothing needs documenting; the description correctly adds no parameter talk and instead spends its words on the return payload.

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: reads the signed-in person's own directory profile, and enumerates its contents (job role, rate, verification state). 'Own' distinguishes it from a generic directory lookup, though it never names a sibling such as directory_capabilities 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?

Usage is only implied: 'the signed-in person's own' tells the agent this is caller-scoped and read-only, but there is no statement of when to call it versus propose_profile_update or directory_capabilities, nor any prerequisite such as authentication.

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