Tangent

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

Annotations already declare readOnly, idempotent, non-destructive, and non-open-world. The description adds the paging model (cursor-based, following filters stay constant) and the shared-filter behavior, which is useful context beyond the safety profile.

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 compact example; the enumeration and routing cue come first and nothing is padded. Every element 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?

An output schema exists, so return values need no explanation. For a read-only, cursor-paged browse tool, the description covers section choice, filter parity, and paging adequately.

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 parameter meaning is already documented. The description adds value by tying the filters to search_resources' filter set and by giving a concrete call example showing vertical/technology/limit usage together.

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 ('newest resources in one section'), enumerates the valid verticals, and explicitly contrasts it with search_resources. An agent can distinguish it from browse-like siblings 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?

Says to use it 'to browse without a query' and notes it shares filters and cursor paging with search_resources, which implies the alternative for query-driven lookups. It stops short of an explicit when-not-to-use statement, 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 already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: no AI calls are made, the brief is read against Tangent's taxonomy and synonyms, result count is capped at 10, and `interpreted_as` reveals how the brief was parsed. It does not discuss latency or failure behavior for an unmatched brief, which is the main remaining gap.

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

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

The what/mechanism/when ordering is front-loaded and each sentence carries information; the trailing example is genuinely illustrative. It is slightly dense in the first sentence, which packs the result shape, the default cap and the `why` semantics into one run-on.

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, brief-driven lookup with a full output schema, the description covers purpose, mechanism, trigger, result fields and an example. Combined with annotations that cover the safety profile, nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents brief, limit and platform in detail; the description's restatement of 'default 8, at most 10' is redundant with the schema. It does add a small amount via the worked example showing how brief and platform are combined, but that is marginal, 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 concrete verb and output ('Turns a design brief into a short list of references') and explains the shape of each result (a `why` explaining the shared pattern/style/category). It is clear what the tool produces, but sibling tools like search_resources or related_resources are never named, so the agent must infer the distinction from the mechanism rather than an explicit statement.

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 trigger: 'Use it when someone describes a screen or product they are about to design,' and notes the combination of taxonomy matching plus search. There is no statement of when NOT to use it or which sibling to pick instead (e.g. keyword search via search_resources), so the guidance is clear but not exclusionary.

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 fully covered. The description adds what the payload contains, but since an output schema exists that content is largely restated rather than new behavioral insight; nothing about caching, rate limits, or failure modes (e.g. unknown slug) 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: payload summary first, then the when-to-use cue, then a copyable example. No filler and the most decision-relevant information leads.

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?

A read-only, single-lookup tool with 100% schema coverage and an output schema — the description covers purpose, contents and a sample call, which is sufficient. It lacks any error behavior for an invalid or unknown slug, a minor remaining gap.

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

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

Schema coverage is 100%, so baseline is 3, but the inline example {"slug": "empty-state", "limit": 8} demonstrates realistic values and pairing beyond the schema's own prose. That concrete call sample is the added value.

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 ('One UI pattern') and enumerates the payload scope: definition, best examples, related patterns, technologies. That is far more informative than the title and lets an agent distinguish it from list_patterns. It stops short of naming sibling tools explicitly, so it is a 4 rather than 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?

'Use it before designing that pattern' is an implied usage cue, not a routing rule. It never contrasts with list_patterns (discovery) or related_resources (graph traversal), so an agent must infer which sibling fits which situation.

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 description adds the genuinely new context: include_image is off by default to save tokens and returns a small WebP thumbnail under ~100 KB. It also clarifies that technologies listed are 'confirmed' rather than inferred, which is real behavioral information.

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 return payload, then the optional flag, then a concrete invocation example. Slightly dense in the field enumeration, but every clause carries information and nothing is 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?

With an output schema present, return-value explanation is not required, yet the description still orients the agent on content. Both parameters are covered and an example is provided; only failure behavior for an unknown slug is left unstated, which is 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 100%, so the schema already documents slug's pattern/example and include_image's default and token rationale. The description restates include_image as a 'small preview of their site' but adds no format or edge-case 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 the exact resource (one person's profile) and enumerates the payload an agent will receive: role, bio, website, social links, studios, confirmed technologies, and Tangent work. The singular scoping ('One person's profile') cleanly separates it from list_people and search_people.

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: supply a slug to fetch one person, and set include_image for a site preview. There is no explicit when-to-use-this-vs-list_people/search_people guidance or any exclusion (e.g. what to do when the slug is unknown).

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/local, so the safety burden is lifted; the description still adds value by scoping what content is fetched and noting the image opt-in for token savings. No contradiction with 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 payload scope, then usage guidance, then a compact invocation example in a few sentences with no filler.

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

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

An output schema exists so return values need no documentation, and the description covers payload scope, usage context, and the optional image cost tradeoff. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so both slug and include_image are already fully documented, and the description's slug example and image mention largely restate that. Baseline 3 is appropriate since it adds little 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 concrete verb+resource and enumerates the returned payload (descriptions, taxonomy, editorial notes, people, related tangents with reasons). This clearly separates it from get_pattern/get_person and list_* siblings 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?

"Use it to go deeper on a search pick" gives a clear situational trigger tied to the search/list siblings. It lacks an explicit when-not or a named alternative tool, 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered without the description. The description adds only that entries carry example counts, which is useful but largely duplicated by the output schema. A 3 is appropriate given the low marginal value over 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?

Two front-loaded sentences that name the resource first and the intended follow-up second, with no padding. The 'Example: {}' fragment is slightly awkward and marginally redundant with the empty schema, 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?

For a no-argument listing tool with a full output schema and complete annotation coverage, the description supplies everything needed: what is listed, what each entry carries, and what to do next. Return-format details are correctly left to the output 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?

The tool takes zero parameters, so the baseline is 4. The trailing 'Example: {}' correctly signals an empty argument object, reinforcing what the empty schema already says; there are no parameters whose meaning needs further explanation.

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 ('Every UI and interaction pattern resources are filed under') and enumerates concrete members (Command Menu, Onboarding, Empty State), so an agent knows exactly what taxonomy it is enumerating. It also names the sibling it feeds into (get_pattern), separating it from browse_vertical and the list_people/list_resources family.

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 to pick a slug for get_pattern' gives an explicit follow-up condition that selects this tool over its siblings. It stops short of stating when NOT to use it (e.g. when you already have a slug and should call get_pattern directly), so it is clear context without full 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-annotation behavior: result ordering (featured first, then alphabetical) and cursor-based paging semantics, which help an agent predict the listing shape.

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 scope and ordering, then the sibling routing, then a compact usage example — every element earns its place. The opening is a verbless fragment, which is slightly less crisp than it could be, 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?

An output schema exists so return values need not be explained, annotations cover the safety profile, and the description supplies the remaining decision-relevant context: ordering, filtering, paging, and the alternative tool. 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%, so all four parameters (role, technology, limit, cursor) are already documented in the schema, including bounds and the next_cursor contract. The description's inline example reinforces the filter combination but adds no semantics 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 the exact resource (designers and design engineers in the catalogue), its ordering rule (featured first, then by name), and its filter/paging capabilities, which lets an agent distinguish it from search_people without opening the schema. It is a specific scope statement rather than a restatement of 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?

It explicitly routes the agent: "Use search_people to find someone by name or focus," naming the sibling and the condition that selects it. Combined with the stated browsing/ordering behavior, an agent can decide between the two tools without 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, non-destructive and closed-world, so the safety profile is covered. The description adds that each result carries a reason string, which is genuinely useful context, but says nothing about result count, ordering, or pagination.

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 clauses, front-loaded with what the tool returns before the usage hint and example. The example duplicates the schema's own example, a small redundancy, but nothing is bloated.

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

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

An output schema exists, so return structure need not be explained, and the single required parameter is fully documented in the schema. The description supplies the semantic hook (why results are related) that makes the output meaningful, leaving only pagination/limits 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 coverage is 100% and the schema itself defines the slug pattern, maxLength, and an example. The description repeats the same example ({"slug": "stripe"}) rather than adding format or constraint detail, 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 operation on a specific resource: returns resources related to one given resource, with the reason for each relation. That is enough to separate it from get_resource (single fetch) and search_resources (query-based), though it never names those siblings 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?

"Use it to follow tangents from a site you like" gives a real usage context, which is more than most definitions offer. However, it never states when NOT to use it or which sibling (search_resources, find_inspiration, get_resource) is the alternative for adjacent needs.

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 safety is covered. The description adds only the ranking behavior ('ranked'); it says nothing about result volume, pagination semantics, or cost/latency beyond what the schema's cursor field implies.

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 sentence plus a compact example, with the core purpose front-loaded and zero filler. Every element 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description covers the search facets and pagination cursor is handled by the schema; only sibling routing is unaddressed, which is 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 100%, so all five parameters are already documented with examples and bounds. The description restates the role/technology filters and gives one combined example, adding marginal meaning beyond the schema. 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 (Find) and resource (designers and design engineers) plus the searchable facets (name, role, focus, stack) and that results are ranked. It does not, however, distinguish itself from siblings like list_people or get_person, leaving the agent to infer the boundary.

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 by the description and the concrete example ({"query": "motion", "role": "design engineer"}), which shows a valid filter combination. But there is no explicit when-to-use guidance and no mention of when to prefer list_people or get_person instead.

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 safety is covered. The description adds genuinely useful behavioral detail beyond that: results are ranked, and results are paginated via cursor. It stops short of describing ranking factors or result shape, but with annotations carrying the safety profile this is a solid contribution.

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 purpose, then usage/alternative, then an example. Every sentence earns its place and nothing is redundant with 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?

An output schema exists, so return values need no explanation. The description covers purpose, filtering, pagination, and the sibling alternative; it omits only secondary details like ranking behavior and result ordering, which is acceptable for this tool's 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%, so the schema already documents each facet, making the baseline 3. The description goes slightly further by grouping the facets into a coherent narrowing list and supplying a concrete invocation example ({query, technology, limit}) that shows how filters combine.

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 ('Ranked search over Tangent's catalogue of design and design-engineering resources') and enumerates the content types covered. It explicitly distinguishes itself from the sibling find_inspiration, 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 a positive condition ('when you know roughly what you want') and an explicit alternative for the contrasting case ('For a whole brief, use find_inspiration'). It also names the narrowing facets, so the agent knows how to constrain the search.

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