Broke It

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 structurally. The description adds the content inventory the tool surfaces, which is useful, but says nothing about caching, freshness, or response shape beyond the field list.

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

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

One sentence, front-loaded with the site identity and then the concrete payload fields. Nothing is redundant with the title or annotations, and no sentence fails to earn 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 parameters, no output schema, and a fully annotated safety profile, this is a simple tool that needs little prose. The description covers the important unknown — what information comes back — though it could note whether the payload includes URLs for feeds and shows.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a parameterless call and does not invent inputs.

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 and resource — it describes the site brokeit.dev — and enumerates the content returned: mission, topics, post count, feeds, and podcast shows. That distinguishes it from siblings like get_post, list_episodes, and latest_news, which each fetch a single content type rather than site-level metadata.

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

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

There is no explicit when-to-use or when-not-to-use statement, and no alternative is named. Usage is only implied: by enumerating feeds and shows, the description signals this is an orientation/overview call that probably precedes choosing a specific sibling 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is covered. The description adds value beyond them by disclosing the shape of the payload an agent gets back (stories, transcript, audio URL), which annotations cannot convey. It omits failure behavior, such as whether an unknown show/date pair returns an error or an empty result.

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

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

A single dense sentence with zero filler, front-loaded with the verb and resource and then fanning out into the returned fields. Slightly list-like within one breath, but nothing needs cutting.

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 return-value burden and does list the main returned artifacts, which is the most important thing for an agent. It is still missing parameter meaning and error/absence behavior for a two-required-parameter lookup 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 0%, so both required parameters (show and date) are documented only by type, enum, and a date pattern, with no prose explaining them. The description never mentions either parameter, so it does not tell an agent that (show, date) together identify an episode or what the date means in that context. It fails to compensate for the coverage gap.

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

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

States a specific verb+resource ("Returns one podcast episode") and enumerates what that entity contains: stories with source links and summaries, the transcript, and the audio URL. It does not distinguish itself from siblings like get_post or list_episodes, so an agent must infer that this is the single-item, episode-level counterpart to list_episodes.

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 "one podcast episode" implies a single-record fetch rather than a listing, which weakly routes an agent away from list_episodes. There is no explicit when-to-use or when-not-to-use guidance, no mention of what to do when the show/date combination has no episode, and no named alternative.

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

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

Annotations already establish that the tool is read-only, idempotent, non-destructive, and closed-world. The description adds useful behavior beyond that: it returns metadata and full text, and bodies over 100,000 characters are truncated with a note. It does not explain not-found or ambiguous lookup behavior, but the added truncation detail is meaningful.

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 two tightly written sentences with no filler. The core return behavior and lookup method are front-loaded, and the truncation caveat follows efficiently.

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

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

For a simple read-only single-resource retrieval tool with strong annotations and no output schema, the description covers what is returned and the main truncation behavior. It is nearly complete, though it could clarify not-found behavior and how slug versus URL selection works if both are provided.

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 description mentions both lookup selectors, slug and URL, which adds some meaning beyond bare property names. The schema describes URL format but leaves slug undocumented, and the description does not explain slug format, precedence if both are supplied, or that neither parameter is required. With 50% schema coverage, this partially compensates but leaves clear gaps.

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

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

The description states a specific verb and resource: returns one brokeit.dev post with metadata and full text. It also distinguishes the tool from list/search siblings by saying it returns one post, and from get_episode by naming post as the resource.

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

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

The description implies usage by saying the post is looked up by slug or URL, which tells the agent this is for retrieving a known post. However, it does not explicitly state when to use this versus search_news, latest_news, or other siblings, nor when not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds behavior beyond that: the result is a merge of newest posts with one newest episode per show, ordering is newest first, and supplying a topic silently drops episodes entirely. That last point is a non-obvious behavioral side effect an agent would otherwise miss.

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 with the composition rule front-loaded and the filter caveat second. Every clause carries information; there is no filler or restatement of the title.

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

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

For a two-parameter, fully documented, annotation-covered read tool, the description covers what is returned at a conceptual level and the one surprising filter behavior. It does not describe the shape of an individual item (fields per post vs. per episode), which would help since there is no output schema, but the 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 coverage is 100%, so baseline is 3, but the description earns extra credit by explaining that topic matches a tag and, crucially, that episodes are omitted when a topic is given — a consequence not stated in the schema's 'Only posts carrying this tag.' The limit parameter's interaction with the merged feed is 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?

The description gives a specific verb and resource set: it lists newest posts on brokeit.dev plus the newest episode of each podcast show, newest first. That is far more precise than the title 'Latest news' and makes the combined posts+episodes output clear. It stops short of naming a sibling such as search_news or list_episodes, so the differentiation is implied rather than explicit.

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

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

Usage is implied by the scope statement (a 'newest items' feed) and by the note that episodes are omitted when a topic is supplied, which is a genuine usage nuance. However, there is no explicit guidance on when to prefer this over search_news, list_episodes, or list_shows, and no stated preconditions.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: results are ordered newest first and each item carries title, duration, story count and audio URL, which tells the agent what a response looks like without an output schema. It leaves truncation/limit behavior and whether history exists uncapped unstated.

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

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

A single front-loaded sentence that states the verb, the scope, the ordering, and the returned fields with no wasted clauses. Nothing could be removed without losing information.

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

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

For a simple two-parameter, non-destructive listing tool with no output schema, the description covers scope, ordering and result shape, which is close to everything an agent needs. The remaining gap is the limit/truncation story and any hint about paging to older episodes.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It clarifies that "show" selects one podcast from the enum and that the list is recency-ordered, but it never mentions the "limit" parameter, so the agent learns nothing about how many episodes are returned, the default of 10, or the maximum of 20 beyond what the schema's constraints state literally.

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

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

The description gives a specific verb and resource ("Lists recent episodes of one podcast show") plus ordering ("newest first") and returned fields, so an agent can tell this is a collection-listing tool. It does not explicitly contrast itself with the sibling get_episode (single episode) or list_shows, leaving that differentiation to inference from the names.

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

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

Usage is only implied: "one podcast show" signals the show-scoped listing case and the sibling names hint that get_episode is for details. There is no sentence saying when to prefer this over get_episode or list_shows, and no note on the default limit or the 20-item cap when an agent needs more.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered elsewhere. The description adds value by disclosing the shape of the response content (per-show language, feed URL, page URL, episode counts), but says nothing about ordering, completeness, or whether all shows are returned.

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

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

One front-loaded sentence with the verb and resource first and the returned fields trailing as supporting detail. No filler or 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 zero-parameter, read-only list tool with no output schema, the description is nearly sufficient: it names the site and the per-show fields, which substitutes for a missing return schema. It could be stronger with a note on whether the list is exhaustive and how to proceed to episodes.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The listed fields describe output rather than inputs, which is harmless given an empty schema.

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

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

States a concrete verb and resource ('Lists the podcast shows') and even enumerates the fields returned (language, feed and page URLs, episode counts). The resource 'shows' is distinguishable from sibling tools like list_episodes and get_episode, but the description never explicitly contrasts itself with them, so it falls short of a 5.

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

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

Usage is only implied: an agent can infer this is the entry point for discovering shows before drilling into episodes. There is no explicit when-to-use statement, no mention of list_episodes/get_episode as follow-ups, and no 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 readOnly, idempotent, non-destructive and closed-world, so the description's job is to add matching behavior — and it does: AND semantics across every word of 3+ letters, plus explicit per-field weights (title 3, tag 2, excerpt/body 1). That tells an agent how to phrase queries and why results are ordered as they are, which is real value beyond the annotation block.

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: scope first, then matching and ranking semantics. Dense and front-loaded with nothing repeated from the schema or annotations.

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

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

For a three-parameter search with no output schema, the description covers what is searched and how matches are scored. It stops short of saying what a result record contains (title, date, url, type) or whether post and episode hits are merged, which would matter 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 coverage is only 33% (only `since` is documented), so the description must compensate, and it does for the most important parameter by defining how `query` is tokenized and matched. `limit` is left entirely to the schema's min/max/default, which is acceptable but keeps this below a 5.

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

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

States a specific verb plus the two resources it covers (brokeit.dev posts and recent podcast stories), which separates it from get_post and latest_news, both of which retrieve rather than keyword-search. It could have named those siblings explicitly, but the search framing is clear enough to route an agent.

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 by the word "Searches" — there is no statement of when to prefer this over latest_news or get_post, no note that results are ranked by the scoring scheme rather than recency. An agent can infer intent but must guess at the boundary cases.

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