Marketingburos

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

With zero annotations, the description carries the full burden. It discloses the output shape (up to 10 candidates with name, legal_name, city, domain), the error response format, and the purpose of the return (slug consumption). It does not mention permissions, rate limits, or side effects, but this is a lookup tool and those details are not critical.

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 uses three sentences that all earn their place: purpose, output, error condition, sibling pointer. It is denser than necessary but not padded, and avoids repeating parameter descriptions already in 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?

No output schema exists, so the description must cover the return contract and it does. It covers error cases, candidate fields, the relationship to get_agency_profile, and reminds of the alternative. Missing bits are minor (e.g., default limit/value range is schema-covered, not description-critical).

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

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

Schema coverage is 100% and the description adds meaning beyond the schema: it clarifies the name/domain mutual requirement (neither given -> error), that 'name' accepts either trade or statutory name, and the domain format. Even with a baseline of 3, the additional context nudges it to 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 verb (find/look up) and a specific resource (one agency) with concrete identifiers (trade name, statutory name, domain). It explicitly contrasts with search_agencies (ranked recommendations) and get_agency_profile (consumer of the slug), so an agent can instantly tell it apart.

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?

Directs when to use: when you need a specific agency's slug, and when not to (search_agencies for ranked recommendations). It also states the requirement that name or domain must be provided, and the condition that triggers an invalid_input error.

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?

With no annotations, the description carries the full behavioral burden. It discloses the error case (returns isError with {error:'not_found'} when slug is invalid or agency opted out) and notes that cultural-fit and cases are read-only (Knowledge-OS canonical). This provides useful behavioral context beyond the simple 'fetch' action, though it stops short of describing success response structure in detail.

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, front-loaded with the primary purpose and key source of input, followed by the error behavior and read-only note. No extraneous words; every sentence earns its place. This is a model of brevity.

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

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

Given there is no output schema, the description sufficiently communicates the expected content (specialisms, cultural-fit axes, up to 3 cases) and error behavior. It does not explicitly state the shape of the success response (e.g., an object with those fields), but for a single-parameter read operation this is a reasonable level of completeness. Slightly more detail on the return structure would push it to a 5.

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

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

The schema already describes the single parameter (slug) with its source and constraints (100% coverage). The description adds no novel information about the slug itself beyond repeating the source of the slug. Since the schema does the heavy lifting, a baseline score of 3 is appropriate; the description's mention of what the profile includes is relevant to output, not the parameter's meaning.

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

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

The description clearly states the action ('Fetch the full public profile') and the resource ('one marketing agency by slug'), and it distinguishes itself from siblings by specifying the source of the slug (from search_agencies or find_agency). This makes it unambiguous which tool to use when a slug is already known.

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 appropriate usage: obtain a slug via search_agencies or find_agency, then call this tool to get the full profile. It does not explicitly state when not to use it or mention alternatives like submit_rfq, but the context is sufficient for an agent to understand the intended workflow. A clear 'use this after you have a slug' signal would be stronger.

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?

With no annotations, the description carries the full load. It discloses restricted specialism taxonomy with unmatched-term echoing, the budget_band non-blocking behavior, the 20-result cap, totalMatched, non-influenceable ranking, and the return rationale in Dutch. This is far beyond basic 'search' semantics.

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

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

The description is dense rather than concise, but each sentence contributes a key behavioral note or parameter nuance. It front-loads the search function and enumerates filters before tying return fields together. It is longer than strictly necessary, 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 an 11-parameter tool with no output schema, this description is remarkably complete: it documents the return fields, the ranking rule, the taxonomy constraint, the budget_band exception, the radius requirement, and the link to get_agency_profile. An agent could safely invoke the tool without access to any structured 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?

Despite 100% schema coverage, the description adds meaning beyond the JSON schema fields: specialisms must come from categories://list taxonomy and unknown terms are echoed in filters, budget_band only excludes conflicting known rates, target_industry is buyer verticals, and near_* only works with within_km. These intended semantics materially affect agent behavior.

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?

Uses a specific 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?

Provides context for when to use the tool and how: it's a discovery search returning slugs, and directs the agent to get_agency_profile for profile details. It also tells the agent to read categories://list for valid specialisms. It does not, however, explicitly state when not to use this tool and when to prefer find_agency, so it stops one step short of an explicit when-not/alternative.

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

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

With no annotations, the description carries the full disclosure burden. It openly states that nothing is sent automatically and that the RFQ is queued for a human operator. It details the success return structure ({rfqId, queuedAgencySlugs, notMatchableSlugs}) and explains that not-matching agencies are skipped rather than causing errors, unless none remain. It enumerates all failure modes with specific payloads (issues[], slugs[], resetAt) and even clarifies the honeypot field via the schema (though not in description—but the behavior is fully covered). This is exceptionally transparent about side effects and error conditions.

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 dense paragraph but is exceptionally well-structured. It front-loads the core purpose, then explains queuing behavior, success returns, and failure modes in a logical order. Every sentence adds critical information — there is no fluff or repetition. The use of semicolons and lists keeps it readable despite its 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?

Given 17 parameters (12 required), no output schema, and no annotations, the description covers what an agent needs to know: the success return shape, the not-matchable behavior, and all error paths with their associated payloads. It also ties in the prerequisite of agency slugs from sibling tools. It does not duplicate schema details, and it explains the queued/human-release nature which is critical for expectation setting. Nothing essential is missing for correct invocation and interpretation of results.

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

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

The schema has 100% description coverage, so the baseline is 3. The description adds a high-level grouping ('v1 wizard profile') and references that selectedAgencySlugs come from sibling tools, but it does not add new meaning beyond what each parameter's schema description already provides. It does not clarify any nuanced formats or interactions beyond the schema, so it stays at the baseline.

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

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

The description states a specific verb ('Submit a Request For Quote'), a clear resource (RFQ to 1-3 agencies via marketingburos.nl), and defines the scope (on behalf of a buyer). It also distinguishes from siblings by noting the input is the wizard profile plus slugs from search_agencies or find_agency, making clear this is the submission step, not discovery. The queuing behavior is also stated, which reinforces the purpose.

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 explains that input requires selectedAgencySlugs from search_agencies or find_agency, implicitly instructing the agent to use those tools first. It also states that nothing is sent automatically and a human operator releases it, giving context on when this is appropriate. However, it does not explicitly say 'use this only when...' or name alternative tools for other actions, so it falls short of explicit when-not guidance, but the indirect routing is clear.

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