Signed

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds real behavioral context beyond the schema: markdown rendering with paragraph/line-break preservation, the exactly-one-target constraint, and the semantic meaning of ai_generated for human-vs-AI attribution.

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

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

Three tight sentences, front-loaded with the core action, then rendering behavior, then the identifier constraint and the ai_generated rule. Each sentence earns its place; the closing clause on visual distinction is slightly wordy but still informative.

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 return values need not be described, and the description covers the target selection rule, body formatting, and the attribution flag. It leaves out edge-case behavior (e.g., supplying both company and person) and any permission/rate context, so it is complete but not exhaustive for a 4-parameter mutation tool.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds meaning the schema lacks: the one-of constraint on company vs person (the schema marks neither as required and has no oneOf), the slug-vs-uuid provenance, and the default/attribution intent of ai_generated. This meaningfully exceeds what the structured fields convey.

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 ('Add a note') and names the three valid target entity types (company, pitch, person), which is more specific than most siblings. It does not explicitly contrast with sibling tools like create_transaction or update_company, so it stops short of full sibling differentiation.

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

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

Gives clear operational context: exactly one of company/person must be supplied, and it points to the tools that yield valid identifiers (list_companies/list_pitches for slugs, list_people for uuids). It also says when to set ai_generated. No explicit when-not-to-use or alternative-tool routing, so it is clear context without full exclusion guidance.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, openWorld=false, so the safety profile is covered. The description goes beyond them by disclosing the default landing stage ('New deals land in triage unless you pass a stage') and dedup behavior ('it's how the deal is deduped against what's already in the account'), which is genuinely useful operational context for a creation 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?

Purpose and the domain rule are front-loaded, and the routing/alternatives come after, which is the right order. It is a little dense (five sentences), and the closing rationale about notes feeding 'the same analysis the deck does' is slightly beyond what the agent needs to invoke the tool, but nothing is wasted.

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

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

For a 13-parameter, zero-required creation tool with annotations and no output schema, the description covers purpose, required-vs-optional input logic, default stage, dedup behavior, and sibling routing. Return-value behavior is not described, but no output schema exists and the create semantics make the outcome predictable.

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 baseline is 3, but the description adds real meaning on the name/domain relationship — 'a domain alone is enough, and the name is derived from it' — clarifying that the no-required-param setup still needs a domain to dedupe. It does not cover the numerous financial parameters, but the schema already does that at full coverage.

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

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

States a specific verb and resource ('Add a deal to the authenticated user's pipeline') and immediately scopes it with a precise qualifier ('a company they've been pitched but haven't invested in'). It explicitly names the sibling it is not (create_transaction), so an agent can distinguish it from the transaction/note tools without opening any schema.

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

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

Gives an explicit when-to-use ('a deal being considered') and when-not ('a company money has actually gone into is create_transaction's job instead'), plus a follow-up recommendation (create_note) with the reason. Routing between the three siblings is unambiguous.

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

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

Annotations only declare the generic write/non-idempotent profile, but the description adds real side effects beyond that: a domain can create a new portfolio company, recording on a pitch converts it to a portfolio position, and passing a valuation_cap also records a valuation mark. It also clarifies that amounts are positive and direction is derived from type, which prevents sign errors.

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?

Four tightly packed sentences, front-loaded with purpose before the targeting rules and side effects. Nearly every clause adds information; the amount/currency phrasing slightly overlaps the schema descriptions but is not wasteful.

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 12-parameter mutation tool with no output schema, the description covers the critical semantics (targeting, sign convention, currency behavior, side effects). It does not describe what is returned (the created transaction/company), which would help, but coverage is otherwise strong given the rich schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning over the schema for several key params: amounts are positive with direction coming from type, currency is the deal currency and should not be converted, and company/domain are alternative targeting mechanisms. Modest but genuine 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?

Names a specific verb and resource ('Record a transaction (cash flow) on a company') and enumerates the exact transaction types (buy, SAFE, sell, distribution), with the buy subtype clarified as equity purchases and capital calls. This clearly distinguishes it from sibling creation tools like create_note and create_pitch.

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 concrete selection conditions: target an existing company by slug, or pass a domain to find-or-create. It also states a non-obvious consequence — recording on a pipeline pitch converts it into a portfolio position. However, it names no alternative tool or exclusion (e.g. when not to use vs. list_transactions), so it stops short of explicit 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?

Beyond the destructiveHint/openWorldHint annotations, the description discloses that the file is purged from storage with no undo, and documents two refusal conditions (founder-update files, files with recorded transactions) plus what the web app does in each case. This is exactly the extra context annotations cannot carry.

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

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

Front-loads the action and the destructive warning before the procedural details, and every sentence carries information. It is somewhat long as a single dense paragraph, which slightly hurts scannability.

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?

The description covers the mutation's irreversibility, the prerequisites (id from list_documents, slug), and the refusal edge cases. With no output schema, 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 description coverage is 100%, so both parameters are already documented, including that the id comes from list_documents and that company is a slug. The description restates this, adding no new syntax or format detail. Baseline 3 applies.

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

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

States a specific verb and resource with scope: removes a document from a company's or pitch's data room. It is clearly distinguishable from upload_document and list_documents, the siblings it could be confused with.

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 instructs to confirm with the user before calling, and names two categories of documents that will be refused rather than handled, routing the agent to the web app for those cases instead. This is genuine when/when-not guidance with alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely new operational facts: there is no undo, user confirmation is required first, only the authenticated user's own notes are reachable (authorization scoping), and an already-deleted note returns not found rather than erroring differently. None of this is recoverable from 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?

Three short sentences, front-loaded with the destructive consequence and the confirm-first instruction before the mechanics. Every sentence carries a distinct payload: irreversibility, precondition, id source, and auth/error behavior. No filler.

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

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

For a single-parameter destructive tool with no output schema, the description covers everything an agent needs: irreversibility, required confirmation, where the id comes from, ownership scoping, and the not-found case. The annotations already carry the safety profile, and nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds non-obvious provenance for the id value: it may also come from the note create_note returned, not only list_notes as the schema states. That saves an unnecessary lookup call and is real added 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?

States a specific verb (delete) and resource (one of the user's notes) with explicit finality ('for good'). An agent can distinguish this from list_notes and create_note, both of which are referenced by function, without opening any schema.

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

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

Gives a clear precondition ('confirm with the user before calling this') and tells the agent where the required id comes from (list_notes, or the note create_note returned). It stops short of naming an explicit alternative or a when-not-to-use condition, so it sits at clear-context rather than full routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's extra value is the payload behavior it discloses: valuation marks and operating metrics are returned newest-first, and runway is derived from them. Consistency between the closed-world annotation and the 'authenticated user's companies' scoping is good; only pagination/size limits remain undisclosed.

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 resource and scope are front-loaded, and with no output schema the payload detail serves a purpose. However, it is delivered as one dense, run-on sentence enumerating a dozen return fields, which is hard to scan and pushes readability limits.

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 conveying what comes back, and it does so thoroughly (position aggregates, valuation history, metrics, people, funds, QSBS clocks, pro rata rights). For a single-required-param read tool this is close to sufficient; only error/empty behavior and result size are unaddressed.

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

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

Schema coverage is 100% for the single 'slug' parameter, so the baseline of 3 applies. The description adds a small amount of provenance beyond the schema ('Slugs come from list_companies / search_companies') but no format or validation semantics.

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

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

The opening clause states a specific resource and scope: one company, fetched by slug, restricted to 'the authenticated user's companies'. That scope plus the payload enumeration lets an agent distinguish it from list_companies/search_companies, which are named as the slug source rather than as equivalent retrieval 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?

It tells the agent where slugs come from (list_companies / search_companies), which is genuine routing help, and the 'authenticated user's companies' scope implicitly rules out arbitrary or third-party companies. But there is no explicit when-to-use-this-vs-X statement and no stated failure mode for an invalid or out-of-scope slug.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, and the description agrees with them. Beyond that, it adds two decision-critical disclosures: only public profiles are returned, and private profiles are indistinguishable from nonexistent ones — preventing the agent from concluding an investor doesn't exist from a not-found result. It also flags the non-obvious trait that the response includes similar investors.

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, each earning its place: scope plus return enumeration, parameter provenance, and the private-profile caveat. The most decision-relevant clause is front-loaded, and no sentence repeats annotation or schema content.

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

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

With one fully documented parameter and rich annotations, the main gap is the missing output schema, which the description compensates for by exhaustively enumerating the response fields. The login-source routing and the private-vs-nonexistent caveat round out everything an agent needs to select and invoke this tool correctly.

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

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

Schema coverage is 100%, and the schema already documents the login parameter including the optional leading '@'. The description adds value above the baseline by stating where valid login values come from (sibling search/list tools or a signed.com URL), which prevents the agent from fabricating or guessing logins.

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 pair — fetching one investor's public Signed profile by login — and enumerates the returned content (bio, sectors, check size, pinned portfolio companies, pitch preferences, follower counts, similar investors). This scoping clearly distinguishes it from sibling tools that enumerate or search collections rather than retrieve a single profile.

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 explicit workflow guidance by naming the login sources: search_investors, list_investors, or a signed.com/@login URL. However, it lacks an explicit 'use this instead of X when Y' exclusion against close siblings like list_investor_followers, so the contextual guidance is clear but not fully formalized.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds context annotations do not: the result is scoped to the authenticated user's own CRM data (an access boundary) and includes relationship types in the returned payload. No output schema exists, so this return-shape detail is genuinely additive.

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

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

Two dense sentences with no filler. The scope constraint and lookup key lead, with the uuid-sourcing hint following, so the most decision-relevant information is 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 single-uuid lookup with full annotations and no output schema, the description covers the resource, access scope, input provenance, and the shape of the relationship data returned. It does not enumerate the other fields the person object likely carries, leaving a small gap for an agent that needs to know exactly what comes back.

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

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

Schema coverage is 100% and the single parameter is documented as 'The person's uuid.', so the baseline is 3. The description goes beyond that by telling the agent which sibling tools produce valid uuid values, which is meaningful usage semantics the schema does not supply.

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 (a CRM person) and pins down the scope with the access qualifier 'one of the authenticated user's' plus a uuid lookup key. It also enumerates the associated payload (company relationships: employee, individual investor, intro source), which separates it from get_company and list_people. The only weakness is an implied rather than explicit verb ('retrieves/returns'), which the name 'defaults to, but the resource and scope are unambiguous.

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

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

It gives clear actionable context by telling the agent exactly where valid uuids originate (list_people, list_notes, get_company), which is a real prerequisite for calling it correctly. It stops short of stating when to prefer this over list_people or search, so there are no explicit exclusions, but the routing guidance is concrete.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description goes further by disclosing a genuine failure mode the annotations cannot express: the analysis is generated only when a deck or founder notes arrive, so empty results are legitimate rather than errors, and `status` must be checked before drawing conclusions.

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 on what the tool returns, then usage, then the empty-result caveat, and every sentence carries information. It is slightly long, with parenthetical glosses ('what stands out') that add a little redundancy, keeping it just short of a 5.

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

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

With no output schema, the description must carry the return-value burden, and it does by enumerating the analysis sections and mentioning the `status` field. Annotations cover the safety profile and there is only one fully documented parameter, so nothing an agent needs in order 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?

There is a single parameter with 100% schema description coverage, so the schema already explains that `slug` identifies the pitch/company. The description adds no syntax, format, or lookup guidance beyond that, 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?

The description names a specific resource (the AI reading of a pitch deck) and enumerates exactly what it returns: highlights, key strengths, founding team, market comparables, open questions, and source documents. This clearly separates it from siblings like get_pitch_email or list_pitches, which deal with raw pitch data rather than the existing analysis.

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

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

It states the trigger condition directly: 'Ask for this before doing diligence on a deal, rather than re-reading the deck from scratch,' naming the alternative behavior it replaces. It also gives an explicit when-not clause: a deal with neither a deck nor founder notes has no analysis, so an empty result should be checked against `status` rather than read as a verdict.

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

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

Annotations already cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description is free to add genuinely new behavior: `email` is null for hand-added or pitch-form deals, `body` is null for emails with no text (e.g., a bare deck), and the email persists with the company after promotion into the portfolio. These edge cases and the data-lifetime rule are not derivable from any structured field.

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

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

The payload of the tool (who sent/forwarded, subject, body) is front-loaded in the first clause, followed by the differentiator and then the null/lifetime caveats. Every sentence carries a distinct fact — no filler or restatement of the tool name.

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 full burden of describing return values and does so field by field (sender, forwarder, subject, stripped body). It also covers the two null cases and the post-promotion persistence, leaving nothing an agent needs to call and interpret this 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?

There is a single `slug` parameter at 100% schema description coverage, so the schema fully documents its meaning ('the pitch (or company) to read, by slug'). The description adds no additional format or resolution detail about the slug beyond what the schema already states, which is the baseline-3 case.

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

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

The description names a specific verb+resource (read the pitch email) and enumerates exactly what is returned: sender, forwarder into Signed, subject, and plain-text body with forwarding headers stripped. It explicitly differentiates itself from the sibling get_pitch_analysis, so an agent can choose between them without opening either schema.

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

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

It states the condition that selects this tool ('read this for the founder's own words — the ask, the traction, who made the intro') and names the alternative that should be used otherwise ('which get_pitch_analysis only summarizes'). Explicit when-to-use plus a named alternative is the top of the scale.

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 useful behavior: results are scoped to the authenticated user and amounts are expressed in the home currency given by `currency`, which the annotations do not 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 metric list, then the currency detail, then the sibling hand-off. Every sentence carries distinct information 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?

With no output schema, the description compensates by enumerating the returned metrics and breakdown dimension and clarifying currency semantics — enough for correct invocation. The only missing piece is disambiguation from get_portfolio_history.

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. There are no inputs whose meaning the description could clarify, and the description correctly implies no filtering arguments are needed.

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?

State a specific verb+resource ('Portfolio-wide metrics for the authenticated user') and enumerates the exact metrics returned (current value, invested, realized, MOIC, DPI, IRR) plus the by_type breakdown. It clearly distinguishes this aggregate view from the per-company listing it routes to via list_companies.

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 provides a concrete routing rule: 'Use list_companies for the per-company rows,' which tells the agent when to prefer the sibling. However, it does not distinguish this tool from get_portfolio_history, another close sibling, leaving one ambiguity for the caller.

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 real behavioral context beyond them: how the series is computed (replaying position snapshots and transactions), the currency semantics (home currency, surfaced as `currency`), and the default downsampling to 60 points.

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

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

Two dense sentences front-load the return content before the computation detail and defaults. No filler; every clause (series contents, computation method, currency, default window/downsampling) carries information.

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

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

There is no output schema, so the description carries the burden of describing the return shape, and it does so fully (dated series with four named series and a currency field) while also covering defaults and computation. All three optional params are documented in the schema, leaving nothing an agent needs 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 `from`, `to`, and `max_points` are already fully documented. The description largely restates the schema defaults and only adds the cumulative-includes-earlier-activity nuance (already in the schema) and the output currency, so it does not meaningfully extend parameter 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 names a specific resource (portfolio value over time for the authenticated user) and enumerates exactly what the series contains: total value, cumulative invested, cumulative realized, and MOIC. The temporal 'over time / dated series' framing cleanly separates it from the point-in-time get_portfolio sibling.

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 rather than stated: the agent can infer this is for historical trends versus a current snapshot, and it notes the default behavior (full history downsampled to 60 points). There is no explicit when-to-use-vs-alternatives guidance or exclusion such as naming get_portfolio for current values.

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 genuinely useful non-obvious semantics beyond that: private profiles return results indistinguishable from nonexistent ones, which tells an agent how to interpret a miss. It stops short of explaining auth requirements or return 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?

Two short sentences, front-loaded with the resource and key, no filler. The only mark against it is that the 'Signed' phrasing is unclear and looks like template residue rather than intentional wording.

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-param read tool with full schema coverage and a complete annotation set, this is close to sufficient, and the private/nonexistent note covers the main edge case. However, with no output schema, the description says nothing about what the profile contains or whether authentication is required ('public Signed' is contradictory), leaving an agent unsure of the access model.

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% with a single documented 'login' parameter, so the schema already carries the parameter meaning. The description's 'by login' only restates the schema and adds no format, casing, or matching guidance.

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 identifies the resource (a user profile) and the lookup key (login), so intent is inferable, but it is framed as a noun phrase rather than a clear verb, and the capitalized 'Signed' reads as garbled/truncated. It does nothing to distinguish itself from close siblings like get_person or whoami, which also return user/person data.

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 statement of when to use this tool versus whoami (current user) or get_person. The only routing-adjacent content is an error-behavior note about private profiles, which is not usage guidance. An agent must guess which of the several get_* profile tools applies.

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 state readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the ranges are ordered 'smallest to largest' and include counts, providing behavioral detail beyond the annotations about ordering and data content.

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

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

The description is a single clear sentence that front-loads the core purpose, then adds ordering and count details. Every element is informative with no redundancy.

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

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

Given no parameters and no output schema, the description fully covers what the tool returns and its relationship to other tools. An agent can correctly decide when to call this tool and what to expect.

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, so there is no parameter information to add. Per the baseline for 0-parameter tools, a score of 4 is appropriate. The description explains the output, which is the semantic content.

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 tool returns check-size ranges, identifies them as the valid values for the check_size filter on specific tools, and includes ordering and count details. It is specific about the resource and how it relates to sibling tools, making it easily distinguishable.

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 explicitly mentions that these are the valid values for the check_size filter on list_investors and search_investors, telling the agent when this tool is useful. It does not explicitly mention alternatives or when not to use it, but the context strongly implies its purpose.

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 the safe-read profile (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint false), so the bar is lower. The description adds real context beyond them: alphabetical ordering, the exact aggregate fields returned, and that multi-filter combinations intersect.

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

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

Two tight sentences: what it returns first, then filter/currency semantics. Dense but front-loaded, with no filler. It could be marginally tighter given the filter list is repeated from the schema.

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

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

With no output schema, the description carries return-value burden and does so reasonably (aggregate fields, ordering, currency). Pagination defaults and max pages live in the schema, so the remaining omission is 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 100%, including enum value explanations and cross-references to list_tags and list_entities, so the baseline of 3 applies. The description restates the filter set without adding format or resolution detail beyond '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 and resource ('List the companies') plus a clear scope ('in the authenticated user's portfolio'), and even enumerates the aggregates returned. It never names the sibling it differs from (search_companies, get_company), but the portfolio scoping implicitly separates it from a general search.

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 documents which dimensions can be filtered and notes that 'filters combine' (AND semantics), which is genuine usage information. However, it gives no when-to-use guidance or routing against search_companies/get_company/list_entities, so the agent must infer the appropriate 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds ordering ('newest first'), provenance of update-attached files (they 'stay on their update and are listed here with its id'), and the fact that content is metadata not bytes. It does not discuss pagination/limits, though the schema does, so a 4 rather than 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?

Dense but front-loaded: the resource and ordering lead, followed by what is returned, then the routing caveat. The first sentence is clause-heavy and slightly run-on, but virtually every phrase carries information (provenance, return fields, alternative tool, slug source).

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 must cover return values and it does — names, types, sizes, and the text-extracted flag, plus the explicit 'not the bytes' caveat. Only pagination/total-count expectations are left implicit, which keeps it short of 5 for a list tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by explaining that the slug is a company or pitch slug sourced from list_companies/list_pitches/search_companies, which the schema only labels generically as 'The company's or pitch's slug.'

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 documents in a company's or pitch's data room') plus scope: files uploaded directly and files attached to founder updates. It also distinguishes itself from the sibling `search` tool, so an agent can route between them 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?

Explicitly says to use 'search with type files' to find a document by its content, and tells the agent where the required slug comes from (list_companies / list_pitches / search_companies). Both the alternative and the prerequisite are spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real context beyond them: which principal is scoped ('authenticated user's'), the default-first ordering, and the tax-status taxonomy. It omits pagination behavior, but that is already documented per-parameter in the schema.

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

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

Two tightly packed sentences with zero filler; scope, ordering, return fields, and the cross-tool linkage are all front-loaded. Nothing repeats the title or name.

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

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

With no output schema, the description carries the return-value burden, and it does partially: default-first ordering, the entity-type examples, and the tax-status enum values. It does not describe the full entity record (ids, names, nesting), so an agent gets the essentials but not the complete response shape.

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% with only page and per_page, both fully described in the schema (defaults and max included). The description adds no syntax or semantic detail about these parameters, 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?

Specific verb+resource ('List the authenticated user's investing entities') with a parenthetical enumerating the concrete kinds (personal accounts, LLCs, trusts, retirement accounts). It also states the ordering rule (default entity first) and the per-row payload (tax status), so an agent knows exactly what it gets. No sibling tool competes for this resource, so there is nothing to confuse it with.

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 closing sentence names the downstream consumers explicitly: 'Entity ids feed the entity filter on list_transactions and list_companies,' which tells the agent why and when it needs this call. There is no when-not-to-use or exclusion, and no mention of prerequisites, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: private accounts are never included, and results are alphabetically sorted by name. It does not mention pagination behavior or result size, keeping it at a 4.

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

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

Two short sentences with zero filler, front-loading the resource and scope, then the exclusion rule. Every clause 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 usefully supplies ordering and the private-account exclusion, and the schema covers pagination. It would be complete with a note on auth context or default page size, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so page and per_page (with defaults and max 100) are already fully documented. The description adds no parameter-level syntax or meaning, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (public users following the authenticated user), and pins down direction with 'following the authenticated user' rather than a generic 'followers'. It does not explicitly distinguish itself from near-siblings like list_follows or list_investor_followers, so it stops short of 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?

Usage is only implied: the agent can infer this is for retrieving one's own follower list, but there is no explicit when-to-use, no prerequisites (e.g. auth requirement), and no pointer to alternatives such as list_follows for the opposite direction.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: results are ordered alphabetically by name, and private accounts are never returned, which tells the agent what data will be missing from the result set. It doesn't cover pagination behavior or result volume.

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

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

Two short sentences with zero filler; the resource and scope are front-loaded, and the exclusion rule follows immediately. Every clause carries information an agent needs.

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

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

For a simple filtered-list tool with full annotation coverage, a complete parameter schema, and no output schema to explain, the description covers resource, ordering, and inclusion criteria. Only minor gaps remain, such as pagination exhaustion behavior or whether the list 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?

Schema description coverage is 100%, and both page and per_page are fully documented in the schema with defaults and max values. The description adds nothing about these parameters, so the baseline 3 applies when the schema does all the work.

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

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

The description names a specific resource (the public accounts the authenticated user follows) and clarifies the direction of the relationship, which is the key distinction from list_followers / list_investor_following. It also states scope and ordering ('alphabetically by name'). It stops short of explicitly naming which sibling to use instead, so it is clear but not fully differentiated from siblings.

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

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

The phrase 'the authenticated user follows' implicitly disambiguates this from list_followers and list_investor_following by establishing the relationship direction, so usage is inferable. However, there is no explicit when-to-use statement, no mention of the sibling list tools, and no guidance on paginating through large follow lists.

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 and idempotentHint, so the description is not required to restate that. It adds the detail about alphabetical ordering and public-only filtering, which is useful but limited; it does not mention pagination behavior or potential edge cases. No contradiction between description and 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 concise (two sentences) and front-loads the core purpose. The sibling context is not explicitly mentioned but the description is efficient without fluff.

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?

The tool is a simple paginated list with a single required parameter, and the schema covers pagination defaults. However, the description lacks explicit guidance on when to use it compared to the similar sibling 'list_investor_following', and there is no output schema to reduce ambiguity about the return structure.

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 covers all parameters with clear descriptions (page, per_page, login). The description does not add additional semantics beyond noting the login can be with or without '@', but this is already in the schema. Thus, baseline of 3 is appropriate.

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

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

The description clearly states the tool lists public signed investors who follow a given investor, sorted alphabetically by name. It mentions the resource (investors/followers) and adds scoping ('public profiles only'), but does not explicitly distinguish it from the sibling 'list_investor_following' (which lists who an investor follows).

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

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

The description gives a clear context (public investors follow a given investor) but does not indicate when to use this tool versus the sibling 'list_investor_following' or others. The example reference to signed.com/@login/followers provides a familiar analogy but no explicit exclusions or alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description adds value beyond them by disclosing alphabetical ordering, the public-profile-only visibility rule, and the UI-equivalent behavior. It does not describe response shape or pagination behavior, but those are partially covered by the 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?

The description is compact and front-loaded: the first sentence states the resource and ordering, and the second adds the public-profile constraint plus a useful UI reference. No filler or redundant phrasing.

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

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

For a read-only list tool with a required login and pagination parameters already documented in the schema, the description covers the core behavioral contract well. The only notable gap is the lack of an explicit contrast with list_investor_followers, though the directionality is clear enough.

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 input schema has 100% description coverage for all parameters, so the baseline is 3. The description adds minimal parameter-level meaning: it identifies login as 'the given investor' and mentions alphabetical ordering, but it does not materially improve on 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?

The description states exactly what the tool does: it lists the public Signed investors a given investor follows, sorted alphabetically. The wording clearly indicates direction ('follows') and distinguishes it from the sibling list_investor_followers.

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 tool is for retrieving a specific investor's following list and clarifies that only public profiles appear. However, it does not explicitly mention when to use this tool over list_investor_followers or other sibling tools, nor does it state 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, and destructiveHint, and the description adds meaningful behavior beyond that: results are ordered by profile completeness, narrowed to one sector or one check size, and each result carries login, investment focus, check sizes, pinned portfolio companies, and pitch status. 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?

Three sentences with no filler: the first states the core purpose and ordering, the second summarizes the payload and relationship to get_investor, and the third routes to the alternative tool. Every sentence earns its place and the most important information is 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 list tool with four optional parameters and no output schema, the description is complete: it covers scope, filtering, ordering, result contents, and the sibling for targeted lookup. An agent has enough context to invoke it correctly and to know what the response will generally contain.

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 baseline is 3; the schema already documents page, sector, per_page, and check_size. The description adds the semantic note that narrowing is to one sector or one check size, which is not stated in the schema. It doesn't need to repeat parameter syntax because the schema already 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?

The description names a specific resource (Signed's public angel investor directory) and a specific action (browse), and adds concrete details: public profiles, ordering by completeness, and optional filters. It explicitly distinguishes itself from search_investors in the final sentence, so an agent can select it correctly without ambiguity.

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 last sentence gives an explicit routing rule: use search_investors when you have a name or keyword. The body clarifies that this tool is for browsing the directory without a specific target and can be narrowed by sector or check size, which is clear when-to-use 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, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real context beyond that: deterministic ordering ('newest first'), the kinds of events included, and that each row carries its repriced company and its own currency — useful for interpreting output without opening a schema (there is none).

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 with the scope and ordering front-loaded, followed by the optional filter and the output currency caveat. No filler, and every sentence carries information an agent can act 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?

With no output schema, the description steps in to describe the row shape (company per mark, currency per row), which is the critical missing piece. Pagination behavior is left to the schema, which documents page/per_page adequately, so the definition is nearly complete for a 3-param list tool.

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

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

Schema description coverage is 100%, so page, per_page, and company are already documented in the schema — baseline is 3. The description restates the company-scoping behavior and adds a currency-per-row detail, but that is a return-value concern rather than parameter semantics, so it does not materially exceed the schema.

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

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

States a specific verb and resource ('List valuation marks across the authenticated user's portfolio') and enumerates the mark types covered — funding rounds, secondaries, estimates, dissolutions. This clearly distinguishes it from siblings like list_metrics, list_transactions, and get_portfolio_history.

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

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

Gives a concrete usage condition: 'Pass a company slug to scope to one company,' which tells the agent how to narrow results. However, it does not name an alternative tool or state when to prefer list_transactions or get_portfolio_history over this one, so the routing guidance is implicit rather than explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real context beyond that: rows are ordered newest first, each row carries its owning company, and amounts are expressed in each company's own currency rather than a normalized one.

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

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

Three sentences, front-loaded with the resource and scope, then a filtering tip, then the currency caveat. No filler and nothing repeated from the schema.

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

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

With no output schema, the description carries the burden of describing return shape, and it does so reasonably: ordering, per-row company attribution, and per-row currency. It stops short of covering pagination behavior or what an empty portfolio returns, leaving minor gaps.

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 page, per_page, and company are already documented in the schema. The description's note that 'company' is a slug largely repeats the schema wording and adds no format or edge-case 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 verb (List) and resource (operating metrics), names concrete examples (ARR, cash, monthly burn), and specifies scope (the authenticated user's portfolio). This clearly distinguishes it from siblings like list_transactions, list_check_sizes, or list_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?

Gives clear context for use (portfolio-wide metrics) and a conditional narrowing path: 'Pass a company slug to scope to one company.' It does not name an alternative tool or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: results come back newest-first and are scoped to the authenticated user, and each note is annotated with its related entity. It does not discuss pagination limits or the absence of results, keeping it short of a 5.

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

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

Two sentences, zero filler, and the highest-value information (resource, ordering, returned fields) is front-loaded before the scoping instruction. Every clause 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 content and it does so (notes with their associated company/pitch/person, newest first). Pagination defaults live in the schema. What remains thin is error/empty-result behavior and whether other filters exist, so a 4 rather than 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?

Schema description coverage is 100%: page, company, and per_page are each documented in the schema, including defaults and max. The description restates the company scoping ('company or pitch') without adding syntax or edge-case meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the authenticated user's notes'), plus the sort order ('newest first') and the shape of each result ('each with the company, pitch, or person it is about'). An agent can distinguish this from list_updates, list_documents, and other list_* siblings without opening a schema.

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

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

Gives clear conditional guidance for the company filter and even names the siblings that produce valid slugs (list_companies / list_pitches), which is genuinely helpful routing. It stops short of saying when to prefer this tool over alternatives such as search or list_updates, so it is not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint false, so safety is covered. The description contributes non-annotation context: the scope is limited to the calling user's own CRM records, results are ordered newest-first, and the returned uuids are the input to get_person. It stops short of describing pagination behavior or result volume.

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

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

Three short sentences, none wasted: scope and ordering first, filterability second, follow-on tool third. Front-loaded and skimmable.

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, but the description compensates by noting the meaningful return field (person uuids) and its downstream use. With annotations covering safety and 100% schema coverage on all seven filters, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so every parameter already has a precise description; the baseline is 3. The description restates the filter categories (name/email text, investor flags, company slug) but adds no syntax, format, or combination guidance beyond what the schema documents.

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

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

Specific verb+resource with scope ('the authenticated user's CRM people'), explicit ordering ('newest first'), and a parenthetical enumerating what a person can be (founders, co-investors, intro sources). An agent can distinguish this from list_investors or search 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?

States the filtering dimensions and adds a chaining hint ('Person uuids feed get_person'), which tells the agent where to go next. It does not, however, explicitly say when to prefer this over the sibling list_investors or the generic search tool, so the routing against close alternatives is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real behavioral context: newest-first ordering, the set of qualifying events, and the semantics of `days_in_previous_stage` including when it is null. It stops short of describing page-size limits or total-count behavior, which the schema partly covers.

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 identity ('as a log of moves, newest first') and keeps the parenthetical on `days_in_previous_stage` tight and necessary. The second sentence earns its place by supplying use cases and the sibling routing, though the whole is on the denser end.

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

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

With no output schema, the description carries the return-value burden and does it well, describing the log entries, ordering, and the meaning of each field mentioned. Minor gaps remain around pagination/result-count behavior, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100% and every parameter (to, from, page, company, per_page, to_stage) is already documented in the schema, including the enum note. The description adds no syntax or filtering detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource (the user's deal pipeline activity) and enumerates exactly what counts as an event: entry, stage change, pass, promotion to portfolio. An agent can distinguish this from sibling list tools and get_company without opening a schema.

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

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

Names the alternative explicitly — one deal's own history lives in get_company under pipeline_history — and frames the use cases as concrete questions ('what moved this week', 'what did I pass on last quarter'). Both the when-to-use and when-to-use-something-else conditions are stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuinely new behavior: the scoping to the authenticated user's pipeline, the newest-first ordering, and the default triage filter. It omits pagination/result-volume behavior, keeping it out of the top score.

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 core action and scope, then the filtering behavior. Every clause earns its place with no redundancy.

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

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

For a read-only list tool whose annotations cover the safety profile and with no output schema to document, the description covers the essential default, ordering, and filtering semantics. Pagination defaults are left to the schema, a minor gap but acceptable.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a semantic the schema lacks: that stage defaults to triage (new, unreviewed) and that all=true means every stage. This clarifies default parameter behavior beyond the raw enum, meriting a modest bump.

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

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

States a specific verb and resource (List pitches), scopes it to the authenticated user's deal pipeline, and specifies ordering (newest first). This clearly distinguishes it from siblings like get_pitch_analysis, get_pitch_email, or create_pitch without ambiguity.

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

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

Gives clear usage context: the default is the triage stage, pass a stage to filter, or all=true for every stage. It does not name alternative tools or state when NOT to use this one, but the selection guidance among its own modes is explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavior: plan gating, currency of amounts, excluded records (sold stock, fund and SPV interests), and explicitly what is NOT reported (exercise cost, side-letter caps/termination terms). This is disclosure well beyond the structured fields.

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

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

Front-loaded with purpose and behaviorally dense throughout, but it is a long paragraph for a three-parameter list tool and a few clauses ('a round nobody can see yet') are stylistic filler. Nearly every sentence still carries signal, so the size is defensible.

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

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

With no output schema, the description carries the return-shape burden and does so: one entry per position, the granting side letter, the ownership it defends, and currency. Exclusions and gating are also covered, leaving no material gap 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?

Schema coverage is 100%, so the baseline is 3; the description still adds meaning to the `company` parameter by explaining that scoping to a slug keeps it available on any plan, which the schema does not convey. Page/per_page are left to the schema.

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

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

States a specific verb+resource (pro rata rights in the authenticated user's portfolio), defines the concept, and specifies ordering ('largest position first'). No sibling lists pro rata rights, so the agent can route to it unambiguously.

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 concrete when-to-use framing ('where the user can follow on', 'which side letters to go find when a round is announced') and a prerequisite: scoping by company slug works on any plan while a full-portfolio sweep needs the Investor plan. It stops short of naming exclusionary cases or alternatives, but there is no competing sibling to route against.

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 read-only/idempotent annotations: it details the OBBBA tiered schedule for post-July-4-2025 stock versus the all-or-nothing 5-year rule for earlier stock, the caps, the exclusion of funds/SPVs, the currency of amounts, and the explicit caveat that it cannot confirm issuer qualification and is not tax advice.

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

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

Front-loaded with purpose, exclusions, and the scoping instruction before the dense tax-schedule detail. The OBBBA tier breakdown is long but substantive rather than padding; a small amount of the statutory detail could be trimmed without loss.

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

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

With no output schema, the description carries the return-shape burden and does so: one lot per acquisition, the exclusion earned today, the dates remaining tiers land, and the currency field. Limitations (recorded dates only, non-advice, funds/SPVs excluded) close the remaining gaps.

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 page, per_page and company are already documented. The description restates the company filter ('Pass a company slug to scope to one company') without adding syntax or edge-case behavior beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — QSBS holding-period clocks across the authenticated user's portfolio — with scope ('one lot per QSBS-flagged acquisition') and ordering ('soonest deadline first'). No sibling tool covers QSBS lots, so the agent can select this without ambiguity.

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

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

Gives a concrete use case ('which positions can be sold without giving up the exclusion') and a scoping instruction for the company param. It lacks explicit when-not guidance or named alternatives, but the sibling set contains no overlapping tool, so the guidance is nearly complete.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds behavioral value beyond annotations by disclosing that results include per-sector counts of public investors, a one-line description, example companies, and ordering by busiest sector first.

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 compact sentence that front-loads the core purpose and then packs the key output details (counts, descriptions, examples) and ordering into the remainder. No filler or repetition of annotation 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 parameterless read-only reference tool with no output schema, the description adequately covers what the response contains and how it is ordered. An agent can predict the tool's output and how to use it with the named sibling filters.

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 input schema has no properties, so the description has no parameter semantics to clarify. The baseline of 4 applies because there is nothing for the description to add over the schema.

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

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

The description clearly identifies the resource ('sectors an investor can list on their Signed profile') and specifies that it returns the valid sector filter values for list_investors and search_investors. It distinguishes the tool from sibling tools by framing it as the reference vocabulary behind their filters rather than an investor-list operation.

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 explicitly connects this tool to the sector filter on list_investors and search_investors, making the intended use clear: consult this before applying sector filters. It does not state when not to use it, but the relationship to the sibling tools is specific enough to guide selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds real behavior the annotations do not: results are scoped to the authenticated user, sorted alphabetically, and tags attached to pitches are listed but excluded from the counts.

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

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

Two sentences, zero filler. The primary purpose and ordering are front-loaded, and the second sentence handles the non-obvious counting caveat and its cross-tool relation in one compact statement.

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 correctly carries the burden of explaining what is returned (tag names plus counts) and the counting nuance. Pagination is left entirely to the schema, and there is no note on ordering relative to pages, but for a two-parameter read tool nothing essential 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% (page and per_page are both documented with defaults and max), so the schema does the heavy lifting. The description adds nothing about pagination semantics or how it interacts with the alphabetical ordering, so the baseline of 3 is appropriate.

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

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

Specific verb (List) plus resource (the authenticated user's tags) with the exact output shape described: alphabetical order and a per-tag count of portfolio companies. It is clearly distinguishable from siblings like list_companies or list_sectors 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?

The description explicitly ties the tool's output to a downstream action: 'Tag names feed the tag filter on list_companies,' which tells the agent why and when to call this. It stops short of stating exclusions or what to do when no tags exist, so it is clear context rather than 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?

Annotations already cover read-only, idempotent, non-destructive status, so the bar is lower; the description still adds real value by disclosing ordering (newest first) and a genuine gotcha: amount is in the row's own currency while amount_home and total_amount_by_type are in the home currency, and the type total covers the full filtered set rather than the page. It stops short of describing pagination/end-of-results behavior, so it is not exhaustive.

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 core action and scope, and no filler. The second sentence is long and dense but each clause (currency semantics, full-set total) carries information an agent cannot get from the schema, so nothing is wasted.

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

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

With no output schema, the description must carry return-value meaning, and it does: it explains amount vs amount_home, the type total scope, and the top-level currency. It omits the shape of other row fields and pagination termination, which are minor gaps for a 7-param filtered list tool.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters including the enum for type and the entity id provenance. The description merely restates the filter set without adding syntax, format, or default detail, so the baseline 3 applies.

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

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

States a specific verb and resource (list the authenticated user's transactions) and enumerates the exact scope: buys, SAFEs, sells, distributions, SAFE conversions, returned newest-first. This cleanly separates it from write siblings like create_transaction and from aggregate siblings like get_portfolio/get_portfolio_history without needing either schema opened.

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 enumerates the available filters (company slug, entity id, type, date range), which implies the intended usage pattern, and 'the authenticated user's transactions' scopes it implicitly to the caller. However, it never states when to prefer this over siblings such as get_portfolio_history or search, nor any exclusion. Adequate but no explicit routing guidance.

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

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

Annotations already declare the read-only, idempotent, non-destructive, closed-world profile, so the safety bar is covered. The description adds genuine behavioral context beyond that: results are newest-first and each carries a plain-text body plus extracted operating metrics. It does not discuss pagination traversal or result-capping behavior, keeping it just under full marks.

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

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

Two tight sentences: the first front-loads what is listed and what is returned, the second covers filtering and id lookup. No filler, no restatement of the name, everything earns its place.

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

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

With no output schema, the description carries the return-value burden and does so by naming the plain-text body and extracted operating metrics. Combined with fully-specified schema params and a complete annotation set, the definition is nearly self-sufficient, missing only notes on pagination response shape.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: slugs come from list_companies/search_companies and the id is the value search returns for update hits. This disambiguates otherwise opaque string and integer params.

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

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

States a specific verb and resource ('List investor updates (founder update emails)'), clarifies scope ('across the authenticated user's portfolio, newest first'), and defines the resource for an agent that may not know what an 'update' is. It also positions itself relative to siblings by naming search as the id source and list_companies/search_companies as slug sources.

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 two usage modes clearly: filter by company slug and/or date range, or fetch a single update by id. It cross-references where ids and slugs come from (search, list_companies/search_companies), which is practical routing guidance. It stops short of explicit when-not-to-use framing, so it is clear context without 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?

The annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds useful context by describing the return shape (a short snippet for each text match) and confirming the search span is the authenticated user's account, but it says nothing about result ordering, truncation, or how matches across types are ranked/merged. Annotations carry most of the weight, so a 3 is appropriate.

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, zero filler. The primary scope statement comes first and the sibling-routing rule is second, so the most decision-relevant information is 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?

There is no output schema, so the description must at least convey what comes back, and it does (a short snippet per text match across the named entity types). It covers scope and the key alternative, but leaves result ordering and any aggregation/truncation behavior unspecified for a multi-type search.

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 q, limit (default 10, max 25) and types are already documented in the schema itself. The description only restates the entity categories and the updates/files distinction, which the schema also conveys, adding no syntax or format detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (Search) plus the exact resource set (portfolio companies, pipeline pitches, people, notes, documents) and the scope of the authenticated user's account in one call. It also distinguishes itself from the sibling search_companies, so an agent can pick between them without opening either schema.

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

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

Explicitly names the alternative (search_companies) and the condition that should route you there: when you only need to resolve a company name to a slug. That is a concrete when-to-use-this-vs-that rule rather than an implied one.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the useful scoping fact that results are limited to the authenticated user's portfolio and pipeline, but says nothing about result size, pagination behavior, or matching 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?

Two sentences, zero padding, and the core purpose is front-loaded before the routing advice. Every clause carries load — the corpus scope, the searchable fields, the filter parity, and the fallback tool.

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

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

For an 8-parameter list/search tool with no output schema, the description covers purpose, scope, routing, and filter parity, and the schema carries all parameter detail. It stops short of describing what a hit looks like or result limits, which would help since no output schema exists.

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 every parameter (q, tag, entity, status, custodian, investment_type, page, per_page) is already documented in the schema. The description only notes that the filter set mirrors list_companies, which adds a cross-reference but no syntax or semantics 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 (search) and resource (the authenticated user's companies), and scopes the corpus explicitly as 'portfolio and pipeline'. It also names the fields searched (name, domain, entity name), so an agent can distinguish it from list_companies and search_investors without opening a schema.

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

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

Explicitly routes the agent: this tool is for a query, and 'for a filter alone with no query, use list_companies.' That is a concrete when-to-use-this vs when-to-use-the-alternative rule tied to a condition the agent can evaluate.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's job is to add context beyond that. It does by stating 'Only public profiles are searched' and noting that sector names in queries also match investors listing that sector. This adds useful behavioral nuance without contradicting the annotations. No contradiction detected.

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, tightly written paragraph. It front-loads the primary purpose, then gives narrowing guidance and an alternative tool reference. Every sentence earns its place, and there is no redundancy or filler.

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

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

For a read-only search tool with no output schema, the description covers the essential information: what is searched, what is excluded (non-public profiles), how to narrow results, and when to use an alternative. It does not need to explain return format since no output schema exists, and the pagination parameters are already in the schema. The description is complete for an agent 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 100%, so all parameters are already documented. The description adds value by explaining how sector and check_size work as filters (narrowing hits) and by referencing list_sectors and list_check_sizes for the full valid sets. This goes beyond a bare schema description, so a 4 is warranted.

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 tool searches Signed's public angel investor directory by keyword, and specifies the fields matched (name, login, bio, investment description, sector names/slugs). It also differentiates from the sibling list_investors by explicitly noting that list_investors is for browsing without a keyword, so an agent can immediately distinguish the two.

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

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

The description gives explicit guidance on when to use this tool versus list_investors ('use list_investors to browse a facet without a keyword') and how to narrow results ('Add sector or check_size to narrow the hits'). It also points to list_sectors and list_check_sizes for valid values, giving the agent a clear path to construct a correct query.

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 annotations already declaring destructiveHint=true and idempotentHint=true, the description adds the key partial-update contract — "Pass only the fields you're changing; everything else is left alone" — plus the non-creating/non-deleting boundary. It stops short of disclosing how destructiveness actually manifests (null clears a field; currency relabel rewrites cost basis), which is left to the schema.

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

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

Front-loaded with the verb and scope, then boundaries and slug provenance; every sentence carries load. The long comma-separated field enumeration in the first sentence partly restates schema-documented fields, which is the one bit of redundancy.

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 17-parameter partial-update tool with annotations but no output schema, the description covers scope, boundaries, the alternative tool, and slug sourcing. What remains unstated (error behavior on invalid combinations, return payload) is minor since update tools rarely need a described return value.

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

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

Schema description coverage is 100%, so the schema already documents all 17 parameters thoroughly, including formats and null semantics; baseline 3 applies. The description adds a useful grouping of fields by intent (identity vs. pipeline vs. round economics), but no format, validation, or edge-case detail beyond what the schema provides.

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 ("Update one of the authenticated user's companies or pitches in place") and enumerates the concrete classes of change (deal_stage, identity fields, deck_url, round economics, position status). It explicitly distinguishes itself from siblings, naming create_transaction for promotion and stating it never creates, deletes, or removes a company.

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

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

Gives explicit when-to-use cases (moving a pitch along the pipeline, correcting identity, attaching a late deck, setting round terms, changing a held position) and names the sibling that owns the adjacent operation (create_transaction for promoting into the portfolio). It also tells the agent where slugs come from (list_companies / list_pitches / search_companies), removing the most common pre-call ambiguity.

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

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

Annotations only cover the safety profile (not read-only, not destructive, not idempotent, closed-world). The description adds substantial behavior beyond that: text-extraction of PDFs/Office/images, re-running deck analysis for multi-page pitch PDFs, and the context cost of base64 bytes. This is rich, non-obvious operational context.

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 the text/content selector first, then usage caveats. It is dense and slightly long, but nearly every sentence carries a distinct constraint (mutual exclusion, link delegation, allowed types, post-processing), so little is wasted.

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

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

With no output schema, the description compensates by covering allowed file types, what happens after upload (text extraction, deck re-analysis), how to source the company/pitch slug, and the link-deck alternative. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds a real constraint not enforced in the schema: exactly one of text or content must be supplied. It also clarifies the filename convention (.md/.txt) and the slug source for company. Genuine added meaning above the schema.

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

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

States a specific verb and resource ('Add a document to a company's or pitch's data room') and immediately anchors it to where uploads land in the web app. It also distinguishes itself from sibling update_company for the linked-deck case, so an agent can route without opening either schema.

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

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

Explicit when-to-use ('Give exactly one of text or content'), explicit when-not-to-use ('For a deck or document that lives at a link, don't upload it: set deck_url with update_company'), and names concrete document types it is meant for (memos, transcripts, user-handed files). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds nothing about auth requirements, side effects, or limits beyond what the annotations state; its field list is closer to return-value documentation than behavioral disclosure.

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

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

Two sentences, zero filler, and the identity of the resource is front-loaded before the routing note. Every clause 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 present, the enumerated field list is exactly the return-value information an agent needs to decide whether this tool satisfies the request. A parameterless, annotation-covered identity read needs nothing more.

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. There is no parameter syntax, format, or validation left for the description to compensate for.

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

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

States a specific resource ('the authenticated Signed user's own profile') and enumerates the returned fields (name, login, email, plan, home currency, investing preferences). The phrase 'authenticated ... own profile' cleanly separates it from the sibling get_user/get_person lookups, and the closing sentence draws the boundary against get_portfolio.

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 away from this tool when aggregate portfolio metrics are wanted ('live on get_portfolio'), which is a genuine alternative-handling signal. It stops short of stating the positive trigger (e.g. 'call this when you need the current caller's identity') or any exclusion involving get_user.

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